diff --git a/CHANGELOG.md b/CHANGELOG.md index e3c150d24..2b8fca13c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang ### Added +- `tepp_api` LineageWeave temporal-context contract (v1): cutoff-safe event eligibility, deterministic event-time ordering, explicit non-causal association/gap boundaries, HTTPS interchange construction, and loopback listener handling at `POST /v1/temporal-context`; read-only context requests no longer require the write-only idempotency header, and no causal inference or completed-result service is included. - `tepp_api` LineageWeave consumer-scoped analysis-run ingress: versioned, credential-free requests use a published consumer identity and isolate idempotency by consumer, tenant workspace, and opaque caller key; the one-shot restack workflow is removed after the protected-main merge is verified. - ADR 0017 records the consumer-scoped analysis-run ingress, its in-memory loopback maturity, and the persistence boundary required before production use. - `tepp_api` naruon live loopback HTTP/1.1 listener: `serve_one` installs a read/write deadline, requires a loopback `Host`, refuses `Transfer-Encoding` and NIM/proxy credential headers, parses `knowledge_cutoff` as RFC 3339 and refuses a future cutoff, keys analysis-run idempotency by tenant plus key, and proves both analysis-run and export POSTs over a real `TcpStream`. Not a production TLS/`$PORT` service (ADR 0011). @@ -77,6 +78,9 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang ### Changed +- The LineageWeave temporal-context read exchange no longer emits a fabricated + `idempotency-key`; that header remains reserved for retryable write/export + operations with a caller-owned operation key. - Removed the temporary PR-155 review-repair workflows and source-fix helper after the bounded repair; subsequent changes use the normal reviewed branch path. - Pinned Rust branch-coverage workflows to `nightly-2026-08-21`, which is newer than the workspace Rust 1.97.1 MSRV and avoids the previous nightly/MSRV mismatch. - Applied the documented `sqlx_live.rs` authored-coverage exclusion to the hourly release gate so live-PostgreSQL success-path coverage is not reported as a false source failure. diff --git a/crates/tepp_api/src/analysis_run_live.rs b/crates/tepp_api/src/analysis_run_live.rs index 1e0748471..d76963f4f 100644 --- a/crates/tepp_api/src/analysis_run_live.rs +++ b/crates/tepp_api/src/analysis_run_live.rs @@ -1,9 +1,10 @@ //! Consumer-neutral live analysis-run ingress for modular CWL services. //! //! This module keeps the Naruon compatibility listener intact while providing -//! the shared `/v1/analysis-runs` boundary needed by Naruon and `LineageWeave`. -//! It accepts transport acknowledgements only; completed psychometric results -//! remain outside this crate. +//! the shared `/v1/analysis-runs` and cutoff-safe `/v1/temporal-context` +//! boundaries needed by Naruon and `LineageWeave`. It accepts transport +//! acknowledgements and temporal evidence context only; completed psychometric +//! results remain outside this crate. use std::collections::HashMap; use std::io::Write; @@ -17,7 +18,8 @@ use crate::live_http::{ use crate::naruon_http::NARUON_ANALYSIS_RUN_PATH; use crate::{ AnalysisRunAccepted, AnalysisRunRequest, ApiError, ErrorEnvelope, NARUON_LIVE_IO_TIMEOUT, - NaruonLiveResponse, requests_are_idempotent_matches, + NaruonLiveResponse, TEMPORAL_CONTEXT_PATH, TemporalContextRequest, build_temporal_context, + requests_are_idempotent_matches, }; #[cfg(test)] @@ -134,9 +136,21 @@ impl AnalysisRunLiveService { fn dispatch_http_request(&mut self, request: &str) -> Result { let (header_block, body) = split_request(request)?; let mut lines = header_block.split("\r\n"); - require_request_line(lines.next().unwrap_or(""))?; + let (method, path) = parse_request_line(lines.next().unwrap_or(""))?; + if method != "POST" || (path != NARUON_ANALYSIS_RUN_PATH && path != TEMPORAL_CONTEXT_PATH) { + return Err(ApiError::InvalidWirePayload); + } let headers = parse_headers(&mut lines)?; - let consumer = require_headers(&headers, self.bound_addr)?; + let consumer = + require_headers(&headers, self.bound_addr, path == NARUON_ANALYSIS_RUN_PATH)?; + if path == TEMPORAL_CONTEXT_PATH { + if consumer != crate::lineageweave_http::LINEAGEWEAVE_CONSUMER_CODE { + return Err(ApiError::InvalidWirePayload); + } + let context_request = TemporalContextRequest::from_json(body)?; + let response = build_temporal_context(&context_request)?; + return Ok(json_response(200, "OK", response.to_json()?)); + } self.accept_analysis_run(consumer, &headers, body) } @@ -175,25 +189,15 @@ impl AnalysisRunLiveService { let request_id = format!("analysis-run-live-{}", self.next_request_serial); self.next_request_serial += 1; let (status_code, reason_phrase) = status_for(error); - json_response( - status_code, - reason_phrase, - error_envelope_json(error, request_id), - ) + let body = error_envelope_json(error, request_id); + json_response(status_code, reason_phrase, body) } } -fn require_request_line(line: &str) -> Result<(), ApiError> { - let (method, path) = parse_request_line(line)?; - if method != "POST" || path != NARUON_ANALYSIS_RUN_PATH { - return Err(ApiError::InvalidWirePayload); - } - Ok(()) -} - fn require_headers( headers: &HashMap, bound_addr: Option, + require_idempotency_key: bool, ) -> Result<&str, ApiError> { validate_common_headers(headers, bound_addr)?; if header_value(headers, "tepp-contract-version")? != "1" { @@ -203,7 +207,9 @@ fn require_headers( if !consumer_is_supported(consumer) { return Err(ApiError::InvalidWirePayload); } - let _idempotency_key = header_value(headers, "idempotency-key")?; + if require_idempotency_key { + let _idempotency_key = header_value(headers, "idempotency-key")?; + } Ok(consumer) } @@ -246,6 +252,7 @@ fn json_response( #[cfg(test)] mod tests { + use std::collections::HashMap; use std::fmt::Write as _; use std::io::{Cursor, Read, Write}; use std::net::TcpStream; @@ -255,14 +262,14 @@ mod tests { use super::{ AnalysisRunLiveService, consumer_tenant_idempotency_key, declared_content_length, error_envelope_json, host_implies_table_access, map_io_error, parse_headers, - read_http_request, require_request_line, split_header_line, split_request, status_for, + read_http_request, require_headers, split_header_line, split_request, status_for, }; use crate::live_http::host_is_loopback; use crate::{ ANALYSIS_RUN_CONTRACT_VERSION, AnalysisRunRequest, ApiError, DEFAULT_ANALYSIS_RUN_BYTE_LIMIT, ErrorEnvelope, LINEAGEWEAVE_CONSUMER_CODE, NARUON_ANALYSIS_RUN_PATH, NARUON_CONSUMER_CODE, NARUON_LIVE_HEADER_BYTE_LIMIT, - NARUON_LIVE_HEADER_COUNT_LIMIT, NARUON_LIVE_IO_TIMEOUT, + NARUON_LIVE_HEADER_COUNT_LIMIT, NARUON_LIVE_IO_TIMEOUT, TEMPORAL_CONTEXT_PATH, }; fn sample_run() -> AnalysisRunRequest { @@ -605,15 +612,80 @@ mod tests { } #[test] - fn parser_helpers_cover_framing_header_and_limit_edges() { + fn temporal_read_headers_and_defensive_write_edges_are_covered() { + let run = sample_run(); + let body = run.to_json().expect("body"); + let mut service = AnalysisRunLiveService::new(); + + for missing_header in ["tepp-contract-version", "tepp-consumer"] { + let headers = [ + ("Host", "127.0.0.1"), + ("content-type", "application/json"), + ("tepp-consumer", NARUON_CONSUMER_CODE), + ("tepp-contract-version", "1"), + ("idempotency-key", run.idempotency_key.as_str()), + ] + .into_iter() + .filter(|(name, _)| *name != missing_header) + .collect::>(); + assert_eq!( + service + .handle_http_request(&http_request(&body, &headers)) + .status_code, + 400, + "missing={missing_header}" + ); + } + + let temporal_body = r#"{"contract_version":1,"consumer_code":"lineageweave","knowledge_cutoff":"2026-08-20T00:00:00Z","subject_post_id":null,"events":[{"event_id":"event-1","source_post_id":"post-1","event_type_code":"order_awarded","event_label":"Order awarded","event_time":"2026-08-01T09:00:00Z","available_time":"2026-08-01T10:00:00Z","project_reference":null,"actor_references":["actor-1"]}]}"#; + let temporal_request = format!( + "POST {TEMPORAL_CONTEXT_PATH} HTTP/1.1\r\nHost: 127.0.0.1\r\ncontent-type: application/json\r\ntepp-consumer: lineageweave\r\ntepp-contract-version: 1\r\ncontent-length: {}\r\n\r\n{temporal_body}", + temporal_body.len() + ); + assert_eq!( + service.handle_http_request(&temporal_request).status_code, + 200 + ); + + let mut headers = HashMap::from([ + ("host".to_owned(), "127.0.0.1".to_owned()), + ("content-type".to_owned(), "application/json".to_owned()), + ("tepp-consumer".to_owned(), NARUON_CONSUMER_CODE.to_owned()), + ("tepp-contract-version".to_owned(), "1".to_owned()), + ]); + assert_eq!( + service.accept_analysis_run(NARUON_CONSUMER_CODE, &headers, &body), + Err(ApiError::InvalidWirePayload) + ); + headers.insert("idempotency-key".to_owned(), run.idempotency_key.clone()); + assert_eq!( + require_headers(&headers, None, true), + Ok(NARUON_CONSUMER_CODE) + ); + headers.insert("tepp-contract-version".to_owned(), "2".to_owned()); assert_eq!( - require_request_line("POST"), + require_headers(&headers, None, true), Err(ApiError::InvalidWirePayload) ); + headers.insert("tepp-contract-version".to_owned(), "1".to_owned()); + headers.insert("tepp-consumer".to_owned(), "unpublished".to_owned()); assert_eq!( - require_request_line("POST /v1/analysis-runs"), + require_headers(&headers, None, true), Err(ApiError::InvalidWirePayload) ); + headers.insert("tepp-consumer".to_owned(), NARUON_CONSUMER_CODE.to_owned()); + let accepted = service + .accept_analysis_run(NARUON_CONSUMER_CODE, &headers, &body) + .expect("accepted"); + assert_eq!(accepted.status_code, 202); + let replay = service + .accept_analysis_run(NARUON_CONSUMER_CODE, &headers, &body) + .expect("replay"); + assert_eq!(replay.body, accepted.body); + } + + #[test] + fn parser_helpers_cover_framing_header_and_limit_edges() { assert_eq!( split_request("").expect_err("empty"), ApiError::InvalidWirePayload diff --git a/crates/tepp_api/src/lib.rs b/crates/tepp_api/src/lib.rs index dbaf90dd2..abf134fe8 100644 --- a/crates/tepp_api/src/lib.rs +++ b/crates/tepp_api/src/lib.rs @@ -22,6 +22,7 @@ mod naruon_http; mod naruon_live; mod orchestration; mod provider_payload; +mod temporal_context; mod wire; /// Analysis-run contract version constant. @@ -65,6 +66,8 @@ pub use lineageweave_http::LINEAGEWEAVE_CONSUMER_CODE; pub use lineageweave_http::NARUON_CONSUMER_CODE; /// Build a credential-free `LineageWeave` analysis-run exchange. pub use lineageweave_http::lineageweave_analysis_run_exchange; +/// Build a credential-free `LineageWeave` temporal-context exchange. +pub use lineageweave_http::lineageweave_temporal_context_exchange; /// Versioned analysis-run path modular consumers may call. pub use naruon_http::NARUON_ANALYSIS_RUN_PATH; /// Versioned export path Naruon may call. @@ -149,3 +152,23 @@ pub use provider_payload::ReidentificationAuditSink; pub use provider_payload::disclose_identity_mapping; /// Minimize evidence for a model provider. pub use provider_payload::minimize_provider_payload; +/// Temporal association claim boundary. +pub use temporal_context::TEMPORAL_ASSOCIATION_CLAIM_BOUNDARY; +/// Temporal-context contract version constant. +pub use temporal_context::TEMPORAL_CONTEXT_CONTRACT_VERSION; +/// Versioned temporal-context HTTP path. +pub use temporal_context::TEMPORAL_CONTEXT_PATH; +/// One opaque event in a temporal-context request. +pub use temporal_context::TemporalContextEvent; +/// One adjacent temporal relation. +pub use temporal_context::TemporalContextRelation; +/// Temporal-context request. +pub use temporal_context::TemporalContextRequest; +/// Temporal-context response. +pub use temporal_context::TemporalContextResponse; +/// One ordered event in a temporal-context response. +pub use temporal_context::TemporalContextTimelineEvent; +/// One non-causal transition-gap candidate. +pub use temporal_context::TemporalTransitionGapCandidate; +/// Build a cutoff-safe, non-causal temporal context. +pub use temporal_context::build_temporal_context; diff --git a/crates/tepp_api/src/lineageweave_http.rs b/crates/tepp_api/src/lineageweave_http.rs index 90d2ab899..44e92b369 100644 --- a/crates/tepp_api/src/lineageweave_http.rs +++ b/crates/tepp_api/src/lineageweave_http.rs @@ -1,6 +1,10 @@ //! Published modular-consumer identity and `LineageWeave` analysis-run exchange. -use crate::{AnalysisRunRequest, ApiError, NaruonHttpExchange, naruon_analysis_run_exchange}; +use crate::naruon_http::compose_https_target; +use crate::{ + AnalysisRunRequest, ApiError, NaruonHttpExchange, TEMPORAL_CONTEXT_CONTRACT_VERSION, + TEMPORAL_CONTEXT_PATH, TemporalContextRequest, naruon_analysis_run_exchange, +}; /// Stable consumer identity used by the Naruon adapter. pub const NARUON_CONSUMER_CODE: &str = "naruon"; @@ -32,6 +36,34 @@ pub fn lineageweave_analysis_run_exchange( Ok(exchange) } +/// Build a credential-free `LineageWeave` temporal-context exchange. +/// +/// # Errors +/// +/// Returns a fail-closed error for a hostile origin or invalid temporal-context +/// request. +pub fn lineageweave_temporal_context_exchange( + origin: &str, + request: &TemporalContextRequest, +) -> Result { + let target_url = compose_https_target(origin, TEMPORAL_CONTEXT_PATH)?; + let body = request.to_json()?; + let headers = vec![ + ("content-type".into(), "application/json".into()), + ("tepp-consumer".into(), LINEAGEWEAVE_CONSUMER_CODE.into()), + ( + "tepp-contract-version".into(), + TEMPORAL_CONTEXT_CONTRACT_VERSION.to_string(), + ), + ]; + Ok(NaruonHttpExchange { + method: "POST", + target_url, + headers, + body, + }) +} + /// Return whether a modular analysis-run consumer is published by TEPP. pub(crate) fn consumer_is_supported(consumer_code: &str) -> bool { matches!( diff --git a/crates/tepp_api/src/naruon_http.rs b/crates/tepp_api/src/naruon_http.rs index 94bca07b5..0765c8ff7 100644 --- a/crates/tepp_api/src/naruon_http.rs +++ b/crates/tepp_api/src/naruon_http.rs @@ -116,7 +116,7 @@ pub fn naruon_may_claim_tepp_inference(method_code: &str) -> Result<(), ApiError } } -fn compose_https_target(origin: &str, path: &str) -> Result { +pub(crate) fn compose_https_target(origin: &str, path: &str) -> Result { require_nonempty(origin)?; if !origin.starts_with("https://") { return Err(ApiError::InvalidWirePayload); @@ -174,7 +174,7 @@ fn refuse_credential_headers(extra_headers: &[(&str, &str)]) -> Result<(), ApiEr Ok(()) } -fn standard_headers(idempotency_key: &str) -> Vec<(String, String)> { +pub(crate) fn standard_headers(idempotency_key: &str) -> Vec<(String, String)> { vec![ ("content-type".into(), "application/json".into()), ("tepp-consumer".into(), "naruon".into()), diff --git a/crates/tepp_api/src/temporal_context.rs b/crates/tepp_api/src/temporal_context.rs new file mode 100644 index 000000000..c4f10c35b --- /dev/null +++ b/crates/tepp_api/src/temporal_context.rs @@ -0,0 +1,414 @@ +//! Versioned, cutoff-safe temporal evidence context for modular consumers. + +use crate::ApiError; +use crate::lineageweave_http::LINEAGEWEAVE_CONSUMER_CODE; +use crate::wire::{ + from_json, require_byte_limit, require_contract_version, require_nonempty, to_json, +}; +use serde::{Deserialize, Serialize}; +use std::collections::HashSet; +use temporal_core::{AvailableTime, EventTime, KnowledgeCutoff, TemporalInstant}; + +/// Supported temporal-context contract version. +pub const TEMPORAL_CONTEXT_CONTRACT_VERSION: u16 = 1; + +/// Versioned temporal-context HTTP path. +pub const TEMPORAL_CONTEXT_PATH: &str = "/v1/temporal-context"; + +/// Claim boundary for temporal association output. +pub const TEMPORAL_ASSOCIATION_CLAIM_BOUNDARY: &str = "association_not_causal"; + +const DEFAULT_TEMPORAL_CONTEXT_BYTE_LIMIT: usize = 64 * 1024; +const MAXIMUM_TEMPORAL_CONTEXT_EVENTS: usize = 1024; + +/// One opaque event offered for cutoff-safe temporal ordering. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct TemporalContextEvent { + /// Opaque event identity. + pub event_id: String, + /// Opaque source-post identity. + pub source_post_id: String, + /// Stable event-type code. + pub event_type_code: String, + /// Bounded display label for the event. + pub event_label: String, + /// Event or valid time. + pub event_time: String, + /// Availability time for historical eligibility. + pub available_time: String, + /// Opaque project identity, when known. + pub project_reference: Option, + /// Opaque actor identities participating in the event. + pub actor_references: Vec, +} + +/// Request for one bounded temporal evidence context. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct TemporalContextRequest { + /// Semantic contract version. + pub contract_version: u16, + /// Published modular-consumer identity. + pub consumer_code: String, + /// Latest availability time permitted in the context. + pub knowledge_cutoff: String, + /// Optional opaque post identity whose event is the subject. + pub subject_post_id: Option, + /// Bounded source events. + pub events: Vec, +} + +/// One ordered event in a temporal context response. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct TemporalContextTimelineEvent { + /// Opaque event identity. + pub event_id: String, + /// Opaque source-post identity. + pub source_post_id: String, + /// Stable event-type code. + pub event_type_code: String, + /// Bounded display label for the event. + pub event_label: String, + /// Original event-time representation. + pub event_time: String, + /// Optional opaque project identity. + pub project_reference: Option, + /// Opaque actor identities. + pub actor_references: Vec, + /// Zero-based deterministic temporal sequence position. + pub sequence_ordinal: usize, + /// Whether this event is associated with the requested subject post. + pub is_subject: bool, +} + +/// One non-causal forward temporal relation in a context response. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct TemporalContextRelation { + /// Earlier event identity. + pub from_event_id: String, + /// Later event identity. + pub to_event_id: String, + /// Stable relation code. + pub relation_code: String, +} + +/// One candidate transition gap that is not a causal claim. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct TemporalTransitionGapCandidate { + /// Earlier event identity. + pub from_event_id: String, + /// Later event identity. + pub to_event_id: String, + /// Explicit non-causal evidence-status code. + pub evidence_status_code: String, +} + +/// Ordered temporal evidence context returned to a modular consumer. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct TemporalContextResponse { + /// Semantic contract version. + pub contract_version: u16, + /// Explicit claim boundary for every relation and gap candidate. + pub claim_boundary: String, + /// Events ordered by absolute event time. + pub timeline_events: Vec, + /// Adjacent forward-only temporal relations. + pub temporal_relations: Vec, + /// Adjacent candidate gaps that are not causal claims. + pub transition_gap_candidates: Vec, + /// Source-post identities in response order. + pub source_post_ids: Vec, +} + +impl TemporalContextRequest { + /// Parse and validate a temporal-context request with the default limit. + /// + /// # Errors + /// + /// Returns a fail-closed wire, version, limit, consumer, time, or shape + /// error. + pub fn from_json(payload: &str) -> Result { + Self::from_json_with_limit(payload, DEFAULT_TEMPORAL_CONTEXT_BYTE_LIMIT) + } + + /// Parse and validate a temporal-context request with a caller limit. + /// + /// # Errors + /// + /// Returns a fail-closed wire, version, limit, consumer, time, or shape + /// error. + pub fn from_json_with_limit(payload: &str, maximum_bytes: usize) -> Result { + require_byte_limit(payload, maximum_bytes)?; + let request: Self = from_json(payload)?; + request.validate()?; + Ok(request) + } + + /// Serialize a temporal-context request after validation. + /// + /// # Errors + /// + /// Returns a fail-closed validation or serialization error. + pub fn to_json(&self) -> Result { + self.validate()?; + to_json(self) + } + + fn validate(&self) -> Result<(), ApiError> { + self.validated_ordered_events().map(|_| ()) + } + + fn validated_ordered_events( + &self, + ) -> Result, ApiError> { + require_contract_version(self.contract_version, TEMPORAL_CONTEXT_CONTRACT_VERSION)?; + if self.consumer_code != LINEAGEWEAVE_CONSUMER_CODE { + return Err(ApiError::InvalidWirePayload); + } + let cutoff = KnowledgeCutoff::parse_rfc3339(&self.knowledge_cutoff) + .map_err(|_| ApiError::InvalidWirePayload)?; + if self.events.is_empty() { + return Err(ApiError::InvalidWirePayload); + } + if self.events.len() > MAXIMUM_TEMPORAL_CONTEXT_EVENTS { + return Err(ApiError::LimitExceeded); + } + if let Some(subject_post_id) = &self.subject_post_id { + require_nonempty(subject_post_id)?; + } + let mut event_ids = HashSet::with_capacity(self.events.len()); + let mut ordered = Vec::with_capacity(self.events.len()); + for event in &self.events { + let event_time = validate_event(event, cutoff.instant(), &mut event_ids)?; + ordered.push((event.clone(), event_time)); + } + if let Some(subject_post_id) = &self.subject_post_id + && !self + .events + .iter() + .any(|event| event.source_post_id == *subject_post_id) + { + return Err(ApiError::InvalidWirePayload); + } + ordered.sort_by(|left, right| { + left.1 + .cmp(&right.1) + .then_with(|| left.0.event_id.cmp(&right.0.event_id)) + }); + Ok(ordered) + } +} + +impl TemporalContextResponse { + /// Parse and validate a temporal-context response. + /// + /// # Errors + /// + /// Returns a fail-closed wire, version, limit, or response-shape error. + pub fn from_json(payload: &str) -> Result { + Self::from_json_with_limit(payload, DEFAULT_TEMPORAL_CONTEXT_BYTE_LIMIT) + } + + /// Parse and validate a temporal-context response with a caller limit. + /// + /// # Errors + /// + /// Returns a fail-closed wire, version, limit, or response-shape error. + pub fn from_json_with_limit(payload: &str, maximum_bytes: usize) -> Result { + require_byte_limit(payload, maximum_bytes)?; + let response: Self = from_json(payload)?; + response.validate()?; + Ok(response) + } + + /// Serialize a temporal-context response after validation. + /// + /// # Errors + /// + /// Returns a fail-closed validation or serialization error. + pub fn to_json(&self) -> Result { + self.validate()?; + to_json(self) + } + + fn validate(&self) -> Result<(), ApiError> { + require_contract_version(self.contract_version, TEMPORAL_CONTEXT_CONTRACT_VERSION)?; + if self.claim_boundary != TEMPORAL_ASSOCIATION_CLAIM_BOUNDARY { + return Err(ApiError::InvalidWirePayload); + } + if self.timeline_events.is_empty() + || self.timeline_events.len() != self.source_post_ids.len() + || self.temporal_relations.len().checked_add(1) != Some(self.timeline_events.len()) + || self.transition_gap_candidates.len().checked_add(1) + != Some(self.timeline_events.len()) + { + return Err(ApiError::InvalidWirePayload); + } + let mut event_ids = HashSet::with_capacity(self.timeline_events.len()); + let mut previous_key: Option<(TemporalInstant, &str)> = None; + for (ordinal, event) in self.timeline_events.iter().enumerate() { + if event.sequence_ordinal != ordinal + || event.event_id.is_empty() + || event.source_post_id.is_empty() + || event.event_type_code.is_empty() + || event.event_label.is_empty() + || event.event_time.is_empty() + || event.actor_references.is_empty() + || self.source_post_ids[ordinal] != event.source_post_id + { + return Err(ApiError::InvalidWirePayload); + } + if !event_ids.insert(event.event_id.clone()) { + return Err(ApiError::InvalidWirePayload); + } + let event_time = EventTime::parse_rfc3339(&event.event_time) + .map_err(|_| ApiError::InvalidWirePayload)? + .instant(); + if let Some((previous_time, previous_id)) = previous_key + && (event_time < previous_time + || (event_time == previous_time && event.event_id.as_str() <= previous_id)) + { + return Err(ApiError::InvalidWirePayload); + } + previous_key = Some((event_time, event.event_id.as_str())); + if let Some(project_reference) = &event.project_reference { + require_nonempty(project_reference)?; + } + for actor_reference in &event.actor_references { + require_nonempty(actor_reference)?; + } + } + for (index, relation) in self.temporal_relations.iter().enumerate() { + if relation.from_event_id != self.timeline_events[index].event_id + || relation.to_event_id != self.timeline_events[index + 1].event_id + || relation.relation_code != "before" + { + return Err(ApiError::InvalidWirePayload); + } + } + for (index, candidate) in self.transition_gap_candidates.iter().enumerate() { + if candidate.from_event_id != self.timeline_events[index].event_id + || candidate.to_event_id != self.timeline_events[index + 1].event_id + || candidate.evidence_status_code != "candidate_not_causal" + { + return Err(ApiError::InvalidWirePayload); + } + } + Ok(()) + } +} + +/// Build an ordered, cutoff-safe temporal context without causal inference. +/// +/// # Errors +/// +/// Returns a fail-closed error when the request contains future-available, +/// duplicate, malformed, or otherwise invalid evidence. +pub fn build_temporal_context( + request: &TemporalContextRequest, +) -> Result { + let ordered = request.validated_ordered_events()?; + let timeline_events = ordered + .iter() + .enumerate() + .map( + |(sequence_ordinal, (event, _))| TemporalContextTimelineEvent { + event_id: event.event_id.clone(), + source_post_id: event.source_post_id.clone(), + event_type_code: event.event_type_code.clone(), + event_label: event.event_label.clone(), + event_time: event.event_time.clone(), + project_reference: event.project_reference.clone(), + actor_references: event.actor_references.clone(), + sequence_ordinal, + is_subject: request + .subject_post_id + .as_ref() + .is_some_and(|subject| subject == &event.source_post_id), + }, + ) + .collect::>(); + let temporal_relations = adjacent_relations(&ordered); + let transition_gap_candidates = adjacent_gaps(&ordered); + let response = TemporalContextResponse { + contract_version: TEMPORAL_CONTEXT_CONTRACT_VERSION, + claim_boundary: TEMPORAL_ASSOCIATION_CLAIM_BOUNDARY.into(), + source_post_ids: timeline_events + .iter() + .map(|event| event.source_post_id.clone()) + .collect(), + timeline_events, + temporal_relations, + transition_gap_candidates, + }; + response.validate()?; + Ok(response) +} + +fn validate_event( + event: &TemporalContextEvent, + cutoff: TemporalInstant, + event_ids: &mut HashSet, +) -> Result { + for value in [ + &event.event_id, + &event.source_post_id, + &event.event_type_code, + &event.event_label, + &event.event_time, + &event.available_time, + ] { + require_nonempty(value)?; + } + if !event_ids.insert(event.event_id.clone()) { + return Err(ApiError::InvalidWirePayload); + } + if let Some(project_reference) = &event.project_reference { + require_nonempty(project_reference)?; + } + if event.actor_references.is_empty() { + return Err(ApiError::InvalidWirePayload); + } + for actor_reference in &event.actor_references { + require_nonempty(actor_reference)?; + } + let event_time = + EventTime::parse_rfc3339(&event.event_time).map_err(|_| ApiError::InvalidWirePayload)?; + let available_time = AvailableTime::parse_rfc3339(&event.available_time) + .map_err(|_| ApiError::InvalidWirePayload)?; + if available_time.instant() > cutoff { + return Err(ApiError::InvalidWirePayload); + } + Ok(event_time.instant()) +} + +fn adjacent_relations( + ordered: &[(TemporalContextEvent, TemporalInstant)], +) -> Vec { + ordered + .windows(2) + .map(|events| TemporalContextRelation { + from_event_id: events[0].0.event_id.clone(), + to_event_id: events[1].0.event_id.clone(), + relation_code: "before".into(), + }) + .collect() +} + +fn adjacent_gaps( + ordered: &[(TemporalContextEvent, TemporalInstant)], +) -> Vec { + ordered + .windows(2) + .map(|events| TemporalTransitionGapCandidate { + from_event_id: events[0].0.event_id.clone(), + to_event_id: events[1].0.event_id.clone(), + evidence_status_code: "candidate_not_causal".into(), + }) + .collect() +} diff --git a/crates/tepp_api/tests/example_contracts.rs b/crates/tepp_api/tests/example_contracts.rs index a286dd98f..592d896da 100644 --- a/crates/tepp_api/tests/example_contracts.rs +++ b/crates/tepp_api/tests/example_contracts.rs @@ -1,7 +1,10 @@ //! Example payloads under `/examples` must parse through the live contracts. use std::path::PathBuf; -use tepp_api::{AnalysisRunRequest, ReproducibilityManifest}; +use tepp_api::{ + AnalysisRunLiveService, AnalysisRunRequest, NARUON_ANALYSIS_RUN_PATH, NaruonLiveService, + ReproducibilityManifest, +}; fn repo_example(name: &str) -> String { let mut path = PathBuf::from(env!("CARGO_MANIFEST_DIR")); @@ -30,3 +33,81 @@ fn committed_examples_parse_through_live_contracts() { .expect("manifest example"); assert_eq!(manifest.engine_version, "0.1.0"); } + +#[test] +fn example_contracts_prove_live_idempotency_and_bound_loopback_identity() { + let mut analysis_service = AnalysisRunLiveService::new(); + let run = AnalysisRunRequest::from_json(&repo_example("analysis_run_request_v1.json")) + .expect("analysis example"); + let body = run.to_json().expect("run json"); + let request = format!( + "POST {NARUON_ANALYSIS_RUN_PATH} HTTP/1.1\r\nHost: 127.0.0.1\r\ncontent-type: application/json\r\ntepp-consumer: naruon\r\ntepp-contract-version: 1\r\nidempotency-key: {}\r\ncontent-length: {}\r\n\r\n{body}", + run.idempotency_key, + body.len() + ); + let accepted = analysis_service.handle_http_request(&request); + assert_eq!(accepted.status_code, 202); + assert_eq!( + analysis_service.handle_http_request(&request).body, + accepted.body + ); + let mut conflict = run.clone(); + conflict.snapshot_id.push_str("-changed"); + let conflict_body = conflict.to_json().expect("conflict json"); + let conflict_request = request + .replace( + &format!("content-length: {}", body.len()), + &format!("content-length: {}", conflict_body.len()), + ) + .replace(&body, &conflict_body); + assert_eq!( + analysis_service + .handle_http_request(&conflict_request) + .status_code, + 400 + ); + + let service = NaruonLiveService::bind_loopback().expect("loopback bind"); + let bound = service.local_addr().expect("bound address"); + let bound_request = |host: &str| { + format!( + "POST {NARUON_ANALYSIS_RUN_PATH} HTTP/1.1\r\nHost: {host}\r\ncontent-type: application/json\r\ntepp-consumer: naruon\r\ntepp-contract-version: 1\r\nidempotency-key: {}\r\ncontent-length: {}\r\n\r\n{body}", + run.idempotency_key, + body.len() + ) + }; + let mut bound_service = service; + assert_eq!( + bound_service + .handle_http_request(&bound_request(&bound.to_string())) + .status_code, + 202 + ); + assert_eq!( + bound_service + .handle_http_request(&bound_request(&bound.ip().to_string())) + .status_code, + 202 + ); + let mut conflicting = run.clone(); + conflicting.snapshot_id.push_str("-changed"); + let conflicting_body = conflicting.to_json().expect("bound conflict json"); + let conflicting_request = bound_request(&bound.to_string()) + .replace( + &format!("content-length: {}", body.len()), + &format!("content-length: {}", conflicting_body.len()), + ) + .replace(&body, &conflicting_body); + assert_eq!( + bound_service + .handle_http_request(&conflicting_request) + .status_code, + 400 + ); + assert_eq!( + bound_service + .handle_http_request(&bound_request("8.8.8.8")) + .status_code, + 403 + ); +} diff --git a/crates/tepp_api/tests/lineageweave_temporal_context_contract.rs b/crates/tepp_api/tests/lineageweave_temporal_context_contract.rs new file mode 100644 index 000000000..a93e94d4c --- /dev/null +++ b/crates/tepp_api/tests/lineageweave_temporal_context_contract.rs @@ -0,0 +1,433 @@ +//! Contract tests for TEPP temporal evidence used by `LineageWeave` Ask surfaces. + +use std::fmt::Write as _; + +use tepp_api::{ + AnalysisRunLiveService, ApiError, LINEAGEWEAVE_CONSUMER_CODE, NARUON_CONSUMER_CODE, + NaruonHttpExchange, TEMPORAL_ASSOCIATION_CLAIM_BOUNDARY, TEMPORAL_CONTEXT_CONTRACT_VERSION, + TEMPORAL_CONTEXT_PATH, TemporalContextEvent, TemporalContextRequest, TemporalContextResponse, + build_temporal_context, lineageweave_temporal_context_exchange, +}; + +fn event( + event_id: &str, + post_id: &str, + event_type: &str, + label: &str, + event_time: &str, + available_time: &str, + actors: &[&str], +) -> TemporalContextEvent { + TemporalContextEvent { + event_id: event_id.into(), + source_post_id: post_id.into(), + event_type_code: event_type.into(), + event_label: label.into(), + event_time: event_time.into(), + available_time: available_time.into(), + project_reference: Some("project-alpha".into()), + actor_references: actors.iter().map(|value| (*value).to_owned()).collect(), + } +} + +fn request() -> TemporalContextRequest { + TemporalContextRequest { + contract_version: TEMPORAL_CONTEXT_CONTRACT_VERSION, + consumer_code: LINEAGEWEAVE_CONSUMER_CODE.into(), + knowledge_cutoff: "2026-08-20T00:00:00Z".into(), + subject_post_id: Some("post-voc".into()), + events: vec![ + event( + "event-voc", + "post-voc", + "voc_received", + "VOC 접수", + "2026-08-01T09:00:00Z", + "2026-08-01T10:00:00Z", + &["actor-support"], + ), + event( + "event-order", + "post-order", + "order_awarded", + "수주", + "2022-03-01T09:00:00Z", + "2022-03-01T10:00:00Z", + &["actor-sales"], + ), + event( + "event-delivery", + "post-delivery", + "delivered", + "납품", + "2024-02-01T09:00:00Z", + "2024-02-01T10:00:00Z", + &["actor-operations"], + ), + event( + "event-spec", + "post-spec", + "specification_changed", + "사양 변경", + "2023-06-01T09:00:00Z", + "2023-06-01T10:00:00Z", + &["actor-engineering"], + ), + ], + } +} + +fn http_request_for_consumer(body: &str, consumer: &str) -> String { + let mut value = format!("POST {TEMPORAL_CONTEXT_PATH} HTTP/1.1\r\n"); + for (name, header_value) in [ + ("Host", "127.0.0.1"), + ("content-type", "application/json"), + ("tepp-consumer", consumer), + ("tepp-contract-version", "1"), + ("idempotency-key", "timeline-001"), + ] { + write!(value, "{name}: {header_value}\r\n").expect("header"); + } + write!(value, "content-length: {}\r\n\r\n{body}", body.len()).expect("body"); + value +} + +fn http_request_from_exchange(exchange: &NaruonHttpExchange) -> String { + let mut value = format!("POST {TEMPORAL_CONTEXT_PATH} HTTP/1.1\r\nHost: 127.0.0.1\r\n"); + for (name, header_value) in &exchange.headers { + write!(value, "{name}: {header_value}\r\n").expect("header"); + } + write!( + value, + "content-length: {}\r\n\r\n{}", + exchange.body.len(), + exchange.body + ) + .expect("body"); + value +} + +#[test] +fn temporal_context_orders_events_and_marks_only_candidate_gaps() { + let response = build_temporal_context(&request()).expect("context"); + assert_eq!(response.contract_version, TEMPORAL_CONTEXT_CONTRACT_VERSION); + assert_eq!(response.claim_boundary, TEMPORAL_ASSOCIATION_CLAIM_BOUNDARY); + assert_eq!( + response + .timeline_events + .iter() + .map(|item| item.event_id.as_str()) + .collect::>(), + vec!["event-order", "event-spec", "event-delivery", "event-voc"] + ); + assert_eq!( + response + .timeline_events + .iter() + .map(|item| item.sequence_ordinal) + .collect::>(), + vec![0, 1, 2, 3] + ); + assert!(response.timeline_events[3].is_subject); + assert_eq!(response.temporal_relations.len(), 3); + assert!( + response + .temporal_relations + .iter() + .all(|item| item.relation_code == "before") + ); + assert!( + response + .transition_gap_candidates + .iter() + .all(|item| item.evidence_status_code == "candidate_not_causal") + ); + assert!( + response + .transition_gap_candidates + .iter() + .any(|item| item.from_event_id == "event-spec" && item.to_event_id == "event-delivery") + ); + assert_eq!( + response.source_post_ids, + vec!["post-order", "post-spec", "post-delivery", "post-voc"] + ); +} + +#[test] +fn temporal_context_rejects_leakage_duplicates_and_unpublished_consumers() { + let mut future = request(); + future.events[0].available_time = "2026-09-01T00:00:00Z".into(); + assert_eq!( + build_temporal_context(&future), + Err(ApiError::InvalidWirePayload) + ); + + let mut duplicate = request(); + duplicate.events[1].event_id = duplicate.events[0].event_id.clone(); + assert_eq!( + build_temporal_context(&duplicate), + Err(ApiError::InvalidWirePayload) + ); + + let mut hostile = request(); + hostile.consumer_code = "unpublished-consumer".into(); + assert_eq!( + build_temporal_context(&hostile), + Err(ApiError::InvalidWirePayload) + ); +} + +#[test] +fn lineageweave_exchange_and_live_listener_return_the_same_context() { + let request = request(); + let exchange = lineageweave_temporal_context_exchange("https://tepp.example.test", &request) + .expect("exchange"); + assert_eq!(exchange.method, "POST"); + assert_eq!( + exchange.target_url, + "https://tepp.example.test/v1/temporal-context" + ); + assert!(exchange.headers.iter().all(|(name, _)| { + !name.eq_ignore_ascii_case("authorization") && !name.to_ascii_lowercase().contains("token") + })); + assert!( + exchange + .headers + .iter() + .all(|(name, _)| !name.eq_ignore_ascii_case("idempotency-key")) + ); + + let mut service = AnalysisRunLiveService::new(); + let response = service.handle_http_request(&http_request_from_exchange(&exchange)); + assert_eq!(response.status_code, 200); + let live = TemporalContextResponse::from_json(&response.body).expect("response"); + assert_eq!(live, build_temporal_context(&request).expect("direct")); +} + +fn single_event_response() -> TemporalContextResponse { + let mut value = request(); + value.events.truncate(1); + value.subject_post_id = None; + build_temporal_context(&value).expect("single event") +} + +fn two_event_response() -> TemporalContextResponse { + let mut value = request(); + value.events.truncate(2); + value.subject_post_id = None; + build_temporal_context(&value).expect("two events") +} + +#[test] +fn temporal_context_rejects_invalid_requests() { + let mut empty_events = request(); + empty_events.events.clear(); + assert_eq!( + build_temporal_context(&empty_events), + Err(ApiError::InvalidWirePayload) + ); + + let mut too_many_events = request(); + too_many_events.events = (0..1025) + .map(|index| { + let mut value = too_many_events.events[0].clone(); + value.event_id = format!("event-{index}"); + value + }) + .collect(); + assert_eq!( + build_temporal_context(&too_many_events), + Err(ApiError::LimitExceeded) + ); + + let mut empty_subject = request(); + empty_subject.subject_post_id = Some(String::new()); + assert_eq!( + build_temporal_context(&empty_subject), + Err(ApiError::InvalidWirePayload) + ); + + let mut unknown_subject = request(); + unknown_subject.subject_post_id = Some("missing-post".into()); + assert_eq!( + build_temporal_context(&unknown_subject), + Err(ApiError::InvalidWirePayload) + ); + + let mut empty_project = request(); + empty_project.events[0].project_reference = Some(" ".into()); + assert_eq!( + build_temporal_context(&empty_project), + Err(ApiError::InvalidWirePayload) + ); + + let mut empty_actors = request(); + empty_actors.events[0].actor_references.clear(); + assert_eq!( + build_temporal_context(&empty_actors), + Err(ApiError::InvalidWirePayload) + ); + + let mut no_project = request(); + no_project.events[0].project_reference = None; + assert!(build_temporal_context(&no_project).is_ok()); +} + +#[test] +fn temporal_context_rejects_invalid_response_shapes() { + let single_response = single_event_response(); + + let mut invalid_claim = single_response.clone(); + invalid_claim.claim_boundary = "causal".into(); + assert_eq!(invalid_claim.to_json(), Err(ApiError::InvalidWirePayload)); + + let mut empty_timeline = single_response.clone(); + empty_timeline.timeline_events.clear(); + assert_eq!(empty_timeline.to_json(), Err(ApiError::InvalidWirePayload)); + + let mut missing_source = single_response.clone(); + missing_source.source_post_ids.clear(); + assert_eq!(missing_source.to_json(), Err(ApiError::InvalidWirePayload)); + + let two_response = two_event_response(); + + let mut missing_relation = two_response.clone(); + missing_relation.temporal_relations.clear(); + assert_eq!( + missing_relation.to_json(), + Err(ApiError::InvalidWirePayload) + ); + + let mut missing_gap = two_response.clone(); + missing_gap.transition_gap_candidates.clear(); + assert_eq!(missing_gap.to_json(), Err(ApiError::InvalidWirePayload)); +} + +#[test] +fn temporal_context_rejects_invalid_response_fields_and_edges() { + let single_response = single_event_response(); + for invalid in [ + { + let mut value = single_response.clone(); + value.timeline_events[0].sequence_ordinal = 1; + value + }, + { + let mut value = single_response.clone(); + value.timeline_events[0].event_id.clear(); + value + }, + { + let mut value = single_response.clone(); + value.timeline_events[0].source_post_id.clear(); + value + }, + { + let mut value = single_response.clone(); + value.timeline_events[0].event_type_code.clear(); + value + }, + { + let mut value = single_response.clone(); + value.timeline_events[0].event_label.clear(); + value + }, + { + let mut value = single_response.clone(); + value.timeline_events[0].event_time.clear(); + value + }, + { + let mut value = single_response.clone(); + value.timeline_events[0].actor_references.clear(); + value + }, + { + let mut value = single_response.clone(); + value.source_post_ids[0] = "different-post".into(); + value + }, + ] { + assert_eq!(invalid.to_json(), Err(ApiError::InvalidWirePayload)); + } + + let two_response = two_event_response(); + for invalid in [ + { + let mut value = two_response.clone(); + value.timeline_events[0].event_time = "2026-08-02T09:00:00Z".into(); + value + }, + { + let mut value = two_response.clone(); + value.timeline_events[1].event_id = value.timeline_events[0].event_id.clone(); + value + }, + { + let mut value = two_response.clone(); + value.timeline_events[0].project_reference = Some(" ".into()); + value + }, + { + let mut value = two_response.clone(); + value.timeline_events[0].actor_references = vec![" ".into()]; + value + }, + { + let mut value = two_response.clone(); + value.temporal_relations[0].from_event_id = "wrong".into(); + value + }, + { + let mut value = two_response.clone(); + value.temporal_relations[0].to_event_id = "wrong".into(); + value + }, + { + let mut value = two_response.clone(); + value.temporal_relations[0].relation_code = "after".into(); + value + }, + { + let mut value = two_response.clone(); + value.transition_gap_candidates[0].from_event_id = "wrong".into(); + value + }, + { + let mut value = two_response.clone(); + value.transition_gap_candidates[0].to_event_id = "wrong".into(); + value + }, + { + let mut value = two_response.clone(); + value.transition_gap_candidates[0].evidence_status_code = "causal".into(); + value + }, + ] { + assert_eq!(invalid.to_json(), Err(ApiError::InvalidWirePayload)); + } +} + +#[test] +fn temporal_context_rejects_equal_timestamp_id_regressions() { + let two_response = two_event_response(); + let mut equal_time = two_response.clone(); + equal_time.timeline_events[1].event_time = equal_time.timeline_events[0].event_time.clone(); + assert!(equal_time.to_json().is_ok()); + + let mut equal_time_out_of_order = equal_time; + equal_time_out_of_order.timeline_events[1].event_id = "event-aaa".into(); + assert_eq!( + equal_time_out_of_order.to_json(), + Err(ApiError::InvalidWirePayload) + ); +} + +#[test] +fn temporal_context_requires_matching_lineageweave_header() { + let body = request().to_json().expect("request json"); + let response = AnalysisRunLiveService::new() + .handle_http_request(&http_request_for_consumer(&body, NARUON_CONSUMER_CODE)); + assert_eq!(response.status_code, 400); +} diff --git a/docs/API_CONTRACT.md b/docs/API_CONTRACT.md index 8980f1ded..d1c61b872 100644 --- a/docs/API_CONTRACT.md +++ b/docs/API_CONTRACT.md @@ -7,7 +7,7 @@ TEPP must work both as a standalone product and as a modular CWL component. Integrations with `naruon`, `contextual-orchestrator`, `.github`, or other repositories use explicit versioned API/artifact contracts. Cross-service direct table access is prohibited. -Current protected main exposes Rust library/domain contracts. The active PR adds a loopback HTTP/1.1 listener for naruon analysis-run and export POSTs. That listener is not a production TLS/`$PORT` service. Endpoint examples below that are not covered by `NaruonLiveService` remain target interface shapes. +Current protected main exposes Rust library/domain contracts. The active PR adds a loopback HTTP/1.1 listener for naruon analysis-run, LineageWeave temporal-context, and export POSTs. That listener is not a production TLS/`$PORT` service. Endpoint examples below that are not covered by `NaruonLiveService` remain target interface shapes. ## 2. Contract families @@ -21,6 +21,7 @@ Current protected main exposes Rust library/domain contracts. The active PR adds | LLM interpretation provider port | `tepp_api` orchestration router + future HTTP gateway | contextual-orchestrator | partial | | model/artifact/export API | `tepp_api` export envelopes + future HTTP service | standalone UI/CWL consumers | partial | | analysis-run request/accepted contracts | `tepp_api` v1 wire DTOs | naruon, orchestrator, UI | active-PR | +| temporal-context ordering contract | `tepp_api` v1 wire DTOs | LineageWeave | active-PR | ## 3. Versioning @@ -42,6 +43,7 @@ When the service layer is introduced, use resources such as: POST /v1/evidence-imports GET /v1/evidence-imports/{import_id} POST /v1/analysis-runs +POST /v1/temporal-context GET /v1/analysis-runs/{run_id} POST /v1/analysis-runs/{run_id}/cancel GET /v1/model-artifacts/{artifact_id} @@ -50,6 +52,12 @@ GET /v1/exports/{export_id} Long-running analysis is durable asynchronous work. `POST /v1/analysis-runs` accepts an idempotency key, immutable input snapshot identity, knowledge cutoff, versioned model contract/configuration, and requested output profile. A retry with the same principal/idempotency key and semantically identical request returns the same run identity; a conflicting body fails closed. +`POST /v1/temporal-context` is a bounded LineageWeave read contract. It accepts +only events whose availability time is at or before `knowledge_cutoff`, orders +them by event time and opaque event ID, and emits adjacent forward temporal +associations plus `candidate_not_causal` transition gaps. It does not infer +causality, mutate TEPP state, or return a completed psychometric result. + ## 5. Analysis request authority An analysis request cannot supply arbitrary facts that bypass validated domain state. The service resolves and validates: diff --git a/docs/TRACEABILITY.md b/docs/TRACEABILITY.md index a3e674cfb..fd2bbb23e 100644 --- a/docs/TRACEABILITY.md +++ b/docs/TRACEABILITY.md @@ -19,7 +19,7 @@ The full APA 7th standards/literature register remains `docs/research/standards- | recovery metrics (RMSE, bias, coverage, graph, temporal order, Monte Carlo SE gates) | PRD; Test Strategy; ADR 0007/0014 | `validation_core` on protected main (PR #19); SE-aware Monte Carlo gates included | implemented-main | | PostgreSQL bitemporal/lineage persistence | ADR 0013; Architecture/ERD | `persistence_postgres` migration contracts, in-memory adapters, live SQL session/document SQL port, tenant RLS (`0002` + session GUC/role helpers), `DATABASE_URL` SQLx gate, optional `live-sqlx` `PgPool` driver, exact-head live PostgreSQL CI with isolation proof, append-only immutability triggers (`0004`), temporal interval ordering CHECKs (`0005`), typed membership assignment (`0006` implemented-main), event-relation/mention/instance SQL (#37–#39 implemented-main), source-artifact SQL (#40 implemented-main), audit-event SQL (#41 implemented-main), concurrent document-write stress (#43 implemented-main), backup/restore integrity revalidation (active PR); remaining physical ERD constraints | partial | | known-truth temporal/event simulation manifests | PRD; TRD; Test Strategy | `tepp_simulation` on protected main; recovery metrics in `validation_core` | implemented-main | -| versioned service/API contracts and exports | PRD; API contract; ADR 0011/0013 | `tepp_api` analysis-run/export/JSON-LD/GraphML contracts on protected main (PR #21); HTTP service remaining accepted-target | partial | +| versioned service/API contracts and exports | PRD; API contract; ADR 0011/0013 | `tepp_api` analysis-run/export/JSON-LD/GraphML contracts on protected main (PR #21); LineageWeave cutoff-safe temporal-context DTO and loopback POST on active PR #158; production TLS remaining | partial | | immutable split/run/reproducibility manifests | ADR 0013; ERD | `tepp_api` reproducibility manifest contract on protected main; `persistence_postgres` append-only SQL insert/lookup for `reproducibility_manifest`, `corpus_split_manifest`, `model_run`, and `model_artifact` (migration `0003`); full physical ERD constraints remaining | partial | | multilingual shared latent semantic space | PRD; ADR 0004 | future semantic/concept/topic crates | accepted-target | | TRSL-TM temporal/relational topic posterior and backend compatibility | ADR 0012; ADR 0004 | future `topic_measurement` | accepted-target |