From 95007d1ed481d39b0484cba17ec06e65c3ef8136 Mon Sep 17 00:00:00 2001 From: Brian Luby Date: Fri, 13 Nov 2026 23:57:00 -0800 Subject: [PATCH 1/2] feat(workspace): S-1 response-file client + M-13 opt-in excerpt export S-1: add POST /api/v2/review-queue/responses writing one immutable portable review response through the shared respond()/RespondOptions path for all four closed families (/1 review, /2 lifecycle, /3 authoring, /4 edit). Preserves loopback, exact-Host pin, project confinement, write-scoped capability and native no-replace publication. New CM-53 writeReviewResponse operation; v1 contract frozen. No new review-family wire contract. M-13: explicit opt-in bounded source excerpts for trace exports. CLI --include-source-excerpts and v2 ExportRequest.include_source_excerpts; the conservative IdsAndHashes default is retained and byte-identical (no excerpts field). Excerpts are trace-only, bounded (100 items, 500 chars), untrusted. Tests: S-1 round-trip + confinement/auth/no-replace refusals; M-13 default byte-identical vs opt-in excerpts. fmt/clippy clean; full suite green except the confirmed-flaky workflow::fake test (passes in isolation, untouched). --- docs/api/capability-matrix-v2.json | 17 +- docs/api/capability-matrix-v2.md | 1 + docs/api/forge-workspace-v2.openapi.yaml | 251 ++++++++++++++++++- src/cli/mod.rs | 27 +- src/cli/trace.rs | 46 +++- src/workspace/actions.rs | 26 +- src/workspace/domain.rs | 48 ++++ src/workspace/http.rs | 10 + src/workspace/http_review.rs | 298 +++++++++++++++++++++++ src/workspace/reports.rs | 136 ++++++++++- tests/api_contract_validation.rs | 4 +- 11 files changed, 842 insertions(+), 22 deletions(-) create mode 100644 src/workspace/http_review.rs diff --git a/docs/api/capability-matrix-v2.json b/docs/api/capability-matrix-v2.json index 16244812..c5dbc09e 100644 --- a/docs/api/capability-matrix-v2.json +++ b/docs/api/capability-matrix-v2.json @@ -553,7 +553,8 @@ "discardProjectSourceTransferStage", "prepareProjectSourceStreamExport", "getProjectSourceStreamExportManifest", - "getProjectSourceStreamExportChunk" + "getProjectSourceStreamExportChunk", + "writeReviewResponse" ], "authorization": "browser-write", "notes": "US-13 completeness entry: a write-capable session (browser or machine) can perform the entire golden path with only these operations (AC-18). This entry intentionally lists every operationId as the exhaustive coverage denominator for CI." @@ -836,5 +837,19 @@ ], "authorization": "browser-read", "notes": "Same-session committed private family only. Every request recaptures and fully verifies exact artifact<=10MiB before returning manifest or<=32KiB part; no supplied-path or HTML-family fallback." + }, + { + "id": "CM-53", + "action": "Write one portable review response file from the interactive client", + "golden_path_step": "cross-cutting", + "user_stories": [ + "US-4", + "US-13" + ], + "operations": [ + "writeReviewResponse" + ], + "authorization": "browser-write", + "notes": "PRD 068 S-1 response-file client over the shared review respond() path for the closed /1 /2 /3 /4 families. Write-scoped capability only; loopback, exact-Host pin, project confinement and native no-replace publication. Asserted identities and quorum never grant domain approval; the portable response wire contract is unchanged." } ] diff --git a/docs/api/capability-matrix-v2.md b/docs/api/capability-matrix-v2.md index a69e485f..b954fe86 100644 --- a/docs/api/capability-matrix-v2.md +++ b/docs/api/capability-matrix-v2.md @@ -153,6 +153,7 @@ The current draft contract declares eight staged-source operations (65 total) an | CM-50 | Discard an unconfirmed source stage | cross-cutting | US-7, US-9, US-10, US-13 | `discardProjectSourceTransferStage` | browser-write | | CM-51 | Prepare and confirm an exact staged-profile source export | cross-cutting | US-7, US-9, US-10, US-13 | `prepareProjectSourceStreamExport`, `getOperation`, `getEffectPreview`, `commitEffectPreview` | browser-write | | CM-52 | Read manifest and exact parts of a committed staged-source export | cross-cutting | US-7, US-9, US-10, US-13 | `getProjectSourceStreamExportManifest`, `getProjectSourceStreamExportChunk` | browser-read | +| CM-53 | Write one portable review response file from the interactive client | cross-cutting | US-4, US-13 | `writeReviewResponse` | browser-write | **CM-48:** API2.4-only staged transport and complete off-Store preview. Whole declaration is reserved; exact part/full hashes, complete native proposed closure and100paths precede confirmation. Source bytes are sensitive; no prefix, native freshness or source approval from transport. diff --git a/docs/api/forge-workspace-v2.openapi.yaml b/docs/api/forge-workspace-v2.openapi.yaml index 4e011d08..20bafbc7 100644 --- a/docs/api/forge-workspace-v2.openapi.yaml +++ b/docs/api/forge-workspace-v2.openapi.yaml @@ -804,7 +804,7 @@ }, "Error": { "additionalProperties": false, - "description": "Closed safe error envelope for the advertised contract revision. Existing code meanings are preserved. API2.1 adds typed cooperative read interruption errors; no capability, absolute path, source excerpt or debug text is retained. API2.2 additionally declares matching pending bundle preparation (409) and direct import deadline/interruption (503). Shutdown retains the existing shutdown-in-progress status; no public import cancellation endpoint. API2.3 adds the four source-restore availability, progress, budget and recovery codes. The separate batch operation distinguishes committed bytes, rollback outcome and cleanup proof; a timeout or not-found lookup is never proof of no write.", + "description": "Closed safe error envelope for the advertised contract revision. Existing code meanings are preserved. API2.1 adds typed cooperative read interruption errors; no capability, absolute path, source excerpt or debug text is retained. API2.2 additionally declares matching pending bundle preparation (409) and direct import deadline/interruption (503). Shutdown retains the existing shutdown-in-progress status; no public import cancellation endpoint. API2.3 adds the four source-restore availability, progress, budget and recovery codes. The separate batch operation distinguishes committed bytes, rollback outcome and cleanup proof; a timeout or not-found lookup is never proof of no write. The S-1 response-file client adds review-response-refused (400) for closed review-contract refusals; no parser prose, private rationale or path escapes.", "examples": [ { "code": "version-conflict", @@ -844,7 +844,8 @@ "bundle-restore-unavailable", "bundle-restore-in-progress", "bundle-restore-budget-exceeded", - "bundle-restore-recovery-required" + "bundle-restore-recovery-required", + "review-response-refused" ], "type": "string" }, @@ -914,6 +915,11 @@ }, "target_path": { "$ref": "#/components/schemas/ProjectRelativePath" + }, + "include_source_excerpts": { + "default": false, + "description": "M-13 explicit opt-in to include bounded source excerpts for resolved trace locations. Only a trace report may set this true; the conservative default (false) exports IDs, hashes and counts only and is byte-identical to the prior envelope. Excerpts are untrusted source content and inherit the source policy's sensitivity.", + "type": "boolean" } }, "required": [ @@ -2764,6 +2770,23 @@ } } } + }, + { + "if": { + "properties": { + "excerpts": {} + }, + "required": [ + "excerpts" + ] + }, + "then": { + "properties": { + "report_kind": { + "const": "trace" + } + } + } } ], "description": "Closed JSON envelope escaped inside canonical workspace static HTML. Runtime also verifies canonical HTML bytes, sorted unique input IDs, and reconciled count invariants. Existing domain report contracts are unchanged.", @@ -2798,7 +2821,47 @@ "schema_version": { "const": "forge.workspace-report/1" }, - "summary": {} + "summary": {}, + "excerpts": { + "description": "M-13 opt-in source excerpts; present only when include_source_excerpts was true on a trace export. Absent in the conservative default envelope.", + "items": { + "additionalProperties": false, + "properties": { + "element_id": { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + "source_file": { + "maxLength": 512, + "minLength": 1, + "type": "string" + }, + "source_line": { + "maximum": 1000000, + "minimum": 1, + "type": "integer" + }, + "text": { + "maxLength": 500, + "type": "string" + }, + "truncated": { + "type": "boolean" + } + }, + "required": [ + "element_id", + "source_file", + "source_line", + "text", + "truncated" + ], + "type": "object" + }, + "maxItems": 100, + "type": "array" + } }, "required": [ "schema_version", @@ -6512,6 +6575,122 @@ "type": "integer", "minimum": 0, "maximum": 319 + }, + "ReviewResponseWriteRequest": { + "additionalProperties": false, + "description": "Closed S-1 response-file declaration reusing the shared review respond() path. All paths are confined project-relative originals; asserted identities never grant domain approval. The portable review response wire contract is unchanged.", + "properties": { + "abstention_reason": { + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "disposition": { + "enum": [ + "approve", + "reject", + "request-changes", + "abstain", + "superseded" + ], + "type": "string" + }, + "family": { + "description": "Closed exchange family selector mirroring the explicit CLI subcommands; the selected family's decoder refuses a mismatched queue original.", + "enum": [ + "review", + "lifecycle", + "authoring", + "edit" + ], + "type": "string" + }, + "item_key": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" + }, + "output": { + "$ref": "#/components/schemas/ProjectRelativePath" + }, + "queue": { + "$ref": "#/components/schemas/ProjectRelativePath" + }, + "rationale_file": { + "$ref": "#/components/schemas/ProjectRelativePath" + }, + "responded_at": { + "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$", + "type": "string" + }, + "response_id": { + "type": "string", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + }, + "reviewer_key": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" + }, + "reviewer_role": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" + }, + "supersedes": { + "additionalProperties": false, + "description": "Explicit self-supersession pair; omission never guesses a predecessor.", + "properties": { + "raw_sha256": { + "pattern": "^[0-9a-f]{64}$", + "type": "string" + }, + "response_id": { + "type": "string", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + } + }, + "required": [ + "response_id", + "raw_sha256" + ], + "type": "object" + } + }, + "required": [ + "family", + "queue", + "rationale_file", + "item_key", + "reviewer_key", + "reviewer_role", + "disposition", + "responded_at", + "response_id", + "output" + ], + "type": "object" + }, + "ReviewResponseWriteResponse": { + "additionalProperties": false, + "description": "Confined publication receipt for one immutable review response file. Publication is native no-replace; an existing destination is refused. Quorum and domain approval remain separate.", + "properties": { + "output": { + "$ref": "#/components/schemas/ProjectRelativePath" + }, + "response_id": { + "type": "string", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + } + }, + "required": [ + "output", + "response_id" + ], + "type": "object" } }, "securitySchemes": { @@ -10473,6 +10652,72 @@ } ] } + }, + "/api/v2/review-queue/responses": { + "post": { + "description": "S-1 interactive response-file client. Writes one immutable portable review response through the same shared respond()/RespondOptions path as `forge review respond`, selecting the closed /1 review, /2 lifecycle, /3 authoring or /4 edit family. Requires a write-scoped capability; loopback transport, exact-Host pin, project confinement and the review contract's own capture/no-replace publication fences apply. Existing destinations are refused; asserted keys/roles and quorum never grant domain approval. No new review-family wire contract.", + "operationId": "writeReviewResponse", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReviewResponseWriteRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReviewResponseWriteResponse" + } + } + }, + "description": "The confined response file was published; the receipt names the exact destination and asserted response id." + }, + "400": { + "description": "Malformed request or closed review-contract refusal (review-response-refused); no private prose or path escapes.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenReadOnly" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "description": "The request body is not application/json.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "capabilityBearer": [] + } + ], + "summary": "Write one confined review response file (S-1)", + "tags": [ + "Review Queue" + ] + } } }, "security": [ diff --git a/src/cli/mod.rs b/src/cli/mod.rs index e6debcf1..0c20b75f 100644 --- a/src/cli/mod.rs +++ b/src/cli/mod.rs @@ -217,6 +217,12 @@ pub enum Commands { /// Composition provenance map used to resolve assembled lines to component instances #[arg(long)] composition_provenance: Option, + + /// M-13 opt-in: include bounded source excerpts for resolved trace + /// locations. Off by default; the conservative report exports IDs and + /// hashes only. The output inherits the source policy's sensitivity. + #[arg(long)] + include_source_excerpts: bool, }, /// Compare two OSCAL artifacts and show differences @@ -3220,14 +3226,19 @@ pub fn execute(cli: &Cli) -> Result<(), ForgeError> { Commands::Drift { committed_artifact, generated_artifact, format } => { run_drift(committed_artifact, generated_artifact, format) } - Commands::Trace { artifact, source, output, composition_provenance } => { - trace::execute_with_composition_provenance( - artifact, - source, - output.as_deref(), - composition_provenance.as_deref(), - ) - } + Commands::Trace { + artifact, + source, + output, + composition_provenance, + include_source_excerpts, + } => trace::execute_with_composition_provenance( + artifact, + source, + output.as_deref(), + composition_provenance.as_deref(), + *include_source_excerpts, + ), Commands::Profile { catalog, include, exclude, format, output, set_params, timestamp } => { let timestamp = timestamp.as_ref().map(chrono::DateTime::to_rfc3339); profile::execute( diff --git a/src/cli/trace.rs b/src/cli/trace.rs index 709a4644..a85b80e0 100644 --- a/src/cli/trace.rs +++ b/src/cli/trace.rs @@ -12,7 +12,7 @@ use crate::trace::generate_trace_report; /// /// Returns `ForgeError` if artifact reading, parsing, or output writing fails. pub fn execute(artifact: &Path, source: &Path, output: Option<&Path>) -> Result<(), ForgeError> { - execute_with_composition_provenance(artifact, source, output, None) + execute_with_composition_provenance(artifact, source, output, None, false) } /// Execute trace reporting with an optional PRD 059 composition provenance bridge. @@ -26,6 +26,7 @@ pub fn execute_with_composition_provenance( source: &Path, output: Option<&Path>, composition_provenance: Option<&Path>, + include_source_excerpts: bool, ) -> Result<(), ForgeError> { let report = generate_trace_report(artifact, source) .map_err(|error| contextualize_trace_input_error(error, artifact, source))?; @@ -35,6 +36,9 @@ pub fn execute_with_composition_provenance( provenance, source, &report, )?); } + if include_source_excerpts { + table.push_str(&format_source_excerpts(&report)?); + } crate::cli::output::write_output(&table, output)?; if let Some(path) = output { @@ -44,6 +48,46 @@ pub fn execute_with_composition_provenance( Ok(()) } +/// M-13 opt-in bounded source excerpts for resolved trace locations. Only the +/// explicit `--include-source-excerpts` flag reaches this; the default report +/// stays IDs/hashes only. Each excerpt is one bounded source line, untrusted. +fn format_source_excerpts( + report: &crate::trace::report::TraceReport, +) -> Result { + use std::fmt::Write as _; + let source = std::fs::read_to_string(&report.source_path).map_err(|error| { + ForgeError::Io(std::io::Error::new( + error.kind(), + format!( + "Failed to read source '{}' for excerpts: {error}", + report.source_path.display() + ), + )) + })?; + let lines: Vec<&str> = source.lines().collect(); + let mut out = String::from("\nSource excerpts (opt-in; untrusted source content):\n"); + let mut count = 0; + for entry in &report.entries { + let Some(trace) = &entry.trace else { continue }; + let Some(line) = trace.source_line else { continue }; + if !crate::trace::resolver::validate_line_reference(Some(line), lines.len()) { + continue; + } + if count >= 100 { + break; + } + count += 1; + let raw = lines[line - 1]; + let mut end = raw.len().min(500); + while !raw.is_char_boundary(end) { + end -= 1; + } + let marker = if end < raw.len() { " …" } else { "" }; + let _ = writeln!(out, " {} (line {line}): {}{marker}", entry.element_id, &raw[..end]); + } + Ok(out) +} + fn contextualize_trace_input_error( error: ForgeError, artifact: &Path, diff --git a/src/workspace/actions.rs b/src/workspace/actions.rs index fd5318de..75edaf3d 100644 --- a/src/workspace/actions.rs +++ b/src/workspace/actions.rs @@ -457,6 +457,18 @@ pub(crate) fn prepare_with_control_for_api( let target = text(request, "target_path")?; output_target(snapshot, target, None)?; let kind = text(request, "report_kind")?; + // M-13 explicit opt-in; v1 never carries the field, so its default + // export stays byte-identical. Only a trace report may carry excerpts. + let include_excerpts = match request.get("include_source_excerpts") { + None => false, + Some(value) if api_major == ApiMajor::V2 => { + value.as_bool().ok_or_else(Error::invalid)? + } + Some(_) => return Err(Error::invalid().into()), + }; + if include_excerpts && kind != "trace" { + return Err(Error::invalid().into()); + } control.checkpoint(Stage::PrepareDomain, ProgressUpdate::Unchanged)?; let summary = match kind { "applicability-gap" => snapshot.classification_counts()?, @@ -468,12 +480,22 @@ pub(crate) fn prepare_with_control_for_api( _ => return Err(Error::invalid().into()), }; control.checkpoint(Stage::PrepareDomain, ProgressUpdate::Unchanged)?; - let bytes = super::reports::render(snapshot, kind, summary)?; + let excerpts = if include_excerpts { + Some(super::domain::trace_excerpts(snapshot)?) + } else { + None + }; + let bytes = super::reports::render_with_excerpts(snapshot, kind, summary, excerpts)?; control.checkpoint(Stage::PrepareDomain, ProgressUpdate::Unchanged)?; let inputs = super::reports::inputs(snapshot, kind)?; control.checkpoint(Stage::PreparePreview, ProgressUpdate::Unchanged)?; let preview = store.preview(root, snapshot, target, "report-export", bytes, &inputs)?; - Ok(operation_reply(store.completed("export",json!({"operation_id":"op_000000000000","preview":preview,"redaction_summary":{"removed_categories":["reviewer-names","absolute-paths","source-excerpts","secrets"]}}))?)) + let removed = if include_excerpts { + json!(["reviewer-names", "absolute-paths", "secrets"]) + } else { + json!(["reviewer-names", "absolute-paths", "source-excerpts", "secrets"]) + }; + Ok(operation_reply(store.completed("export",json!({"operation_id":"op_000000000000","preview":preview,"redaction_summary":{"removed_categories":removed}}))?)) } _ => { Err(Error::new("not-found", "The requested effect operation was not found.", false) diff --git a/src/workspace/domain.rs b/src/workspace/domain.rs index 422a3384..f66c2a2f 100644 --- a/src/workspace/domain.rs +++ b/src/workspace/domain.rs @@ -506,6 +506,54 @@ pub(crate) fn trace_counts(snapshot: &Snapshot) -> Result { ) } +/// Bounded source line length for opt-in excerpts; longer lines are truncated. +const EXCERPT_LINE_MAX: usize = 500; +/// Complete opt-in excerpt ceiling; further resolved locations are omitted. +const EXCERPT_MAX: usize = 100; + +/// M-13 opt-in source excerpts for resolved trace locations. Only an explicit +/// sensitive export calls this; the conservative default exports IDs/hashes only. +/// Each excerpt is one bounded source line, labeled untrusted, never approval proof. +pub(crate) fn trace_excerpts(snapshot: &Snapshot) -> Result> { + let mut excerpts = Vec::new(); + for item in snapshot.items.iter().filter(|item| { + matches!(item.registration.role, Role::OscalCatalogArtifact | Role::OscalComponentArtifact) + }) { + for entry in trace_entries(item)? { + let Some(trace) = entry.trace else { continue }; + let Some(source) = trace_source(snapshot, &trace) else { continue }; + let text = std::str::from_utf8(&source.captured.bytes).map_err(|_| invalid())?; + let lines: Vec<&str> = text.lines().collect(); + if !crate::trace::resolver::validate_line_reference(trace.source_line, lines.len()) { + continue; + } + let Some(line) = trace.source_line else { continue }; + if excerpts.len() >= EXCERPT_MAX { + return Ok(excerpts); + } + let raw = lines[line - 1]; + let truncated = raw.len() > EXCERPT_LINE_MAX; + let text = if truncated { + let mut end = EXCERPT_LINE_MAX; + while !raw.is_char_boundary(end) { + end -= 1; + } + &raw[..end] + } else { + raw + }; + excerpts.push(serde_json::json!({ + "element_id": entry.element_id, + "source_file": trace.source_file, + "source_line": line, + "text": text, + "truncated": truncated, + })); + } + } + Ok(excerpts) +} + /// Convert one captured policy source using the existing deterministic domain /// pipeline and suppressed source-bearing logger. Temporary copies and pipeline /// calls are cooperative boundaries; no parser preemption or publication occurs. diff --git a/src/workspace/http.rs b/src/workspace/http.rs index f31fd672..c098c691 100644 --- a/src/workspace/http.rs +++ b/src/workspace/http.rs @@ -24,6 +24,9 @@ use super::session::{Mode, Session}; #[path = "http_source.rs"] mod source; +#[path = "http_review.rs"] +mod review; + #[path = "http_staged.rs"] mod staged; @@ -961,6 +964,13 @@ fn dispatch( state.stopped.store(true, Ordering::Release); return json_response(json!({"state":"shutting-down"}), "ShutdownResponse"); } + if method == "POST" && path == "/api/v1/review-queue/responses" { + return review::write_response( + state, + payload.as_ref().ok_or_else(Error::invalid)?, + read_deadline, + ); + } if state.api_major == ApiMajor::V2 && method == "GET" && let Some(route) = ReadQuery::route(path) diff --git a/src/workspace/http_review.rs b/src/workspace/http_review.rs new file mode 100644 index 00000000..19ceedf9 --- /dev/null +++ b/src/workspace/http_review.rs @@ -0,0 +1,298 @@ +//! S-1 interactive response-file client: one confined synchronous write through +//! the same shared review `respond()` path the CLI uses. The portable response +//! wire contract is unchanged; asserted identities never grant domain approval. + +use super::*; +use crate::review::commands::{RespondOptions, Supersedes}; +use crate::review::wire::Disposition; +use crate::workspace::{index, root}; +use serde::Deserialize; +use std::path::Path; + +/// Closed family selector mirroring the explicit CLI subcommands; the selected +/// family's own decoder still refuses a mismatched queue original. +#[derive(Deserialize)] +#[serde(rename_all = "kebab-case")] +enum ReviewFamily { + /// Mapping/applicability `/1` exchange (`forge review respond`). + Review, + /// Lifecycle `/2` exchange. + Lifecycle, + /// Authoring `/3` exchange. + Authoring, + /// Edit-capable `/4` exchange. + Edit, +} + +/// Explicit self-supersession pair; omission never guesses a predecessor. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct SupersedesRequest { + response_id: String, + raw_sha256: String, +} + +/// Closed request envelope; every path is project-root relative and confined. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct ReviewResponseRequest { + family: ReviewFamily, + queue: String, + rationale_file: String, + item_key: String, + reviewer_key: String, + reviewer_role: String, + disposition: Disposition, + responded_at: String, + response_id: String, + #[serde(default)] + abstention_reason: Option, + #[serde(default)] + supersedes: Option, + output: String, +} + +/// Fixed safe refusal; no review parser prose, private rationale or path escapes. +fn refused() -> Error { + Error::new( + "review-response-refused", + "The closed review contract refused this response declaration.", + false, + ) +} + +/// Publish one immutable response file through the shared review command path. +/// Session write scope, exact-Host pin and loopback transport are already +/// enforced by the parent guard; this handler adds project confinement and the +/// review contract's own capture/publication fences. +pub(super) fn write_response( + state: &State, + payload: &Value, + read_deadline: Option, +) -> Result>> { + let request: ReviewResponseRequest = + serde_json::from_value(payload.clone()).map_err(|_| Error::invalid())?; + for path in [&request.queue, &request.rationale_file, &request.output] { + index::validate_path(path)?; + } + // Participating exclusive lease: the response is a new project file, and + // concurrent workspace effects must not interleave with its publication. + let _io = source::project_write(state)?; + let root_path = state.root.project_path(); + let supersedes = request + .supersedes + .as_ref() + .map(|prior| Supersedes { response_id: &prior.response_id, raw_sha256: &prior.raw_sha256 }); + let options = RespondOptions { + project_root: root_path, + queue: Path::new(&request.queue), + rationale_file: Path::new(&request.rationale_file), + item_key: &request.item_key, + reviewer_key: &request.reviewer_key, + reviewer_role: &request.reviewer_role, + disposition: request.disposition, + responded_at: &request.responded_at, + response_id: &request.response_id, + abstention_reason: request.abstention_reason.as_deref(), + supersedes, + proposed_patch: None, + output: Path::new(&request.output), + }; + let mut control = ReadControl { state, deadline: read_deadline, interruption: None }; + let result = match request.family { + ReviewFamily::Review => crate::review::commands::respond(&options, &mut control), + ReviewFamily::Lifecycle => { + crate::review::lifecycle_commands::respond(&options, &mut control) + } + ReviewFamily::Authoring => { + crate::review::authoring_commands::respond(&options, &mut control) + } + ReviewFamily::Edit => crate::review::edit_commands::respond(&options, &mut control), + }; + match result { + Ok(()) => json_response_for( + state.api_major, + json!({"output": request.output, "response_id": request.response_id}), + "ReviewResponseWriteResponse", + ), + Err(crate::review::commands::CommandError::Publication) => Err(root::publish_failed()), + Err(_) => Err(refused()), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::review::applicability_capture::tests::Fixture; + use crate::review::commands::InitOptions; + use crate::review::decode::{self, ContractLedger}; + use crate::workspace::preparation::NoopControl; + use std::sync::{Arc, Mutex, RwLock, atomic::AtomicBool}; + + const RESPONSE_ID: &str = "66666666-6666-4666-8666-666666666666"; + + /// Production always supplies a real admission budget; `None` means expired. + fn budget() -> Option { + Instant::now().checked_add(Duration::from_secs(10)) + } + + /// One machine-write session over a genuine initialized review fixture root. + fn machine_state(root: Root, read_only: bool) -> State { + State { + api_major: ApiMajor::V2, + root, + project_io: RwLock::new(()), + restores: None, + host: "127.0.0.1:1".into(), + origin: "http://127.0.0.1:1".into(), + session: Mutex::new(Session::new(Mode::Machine, read_only, None).unwrap()), + stopped: AtomicBool::new(false), + rate: Mutex::new((Instant::now(), 0)), + effects: Mutex::new(crate::workspace::effects::Store::default()), + work: Arc::new(tokio::sync::Semaphore::new(2)), + jobs: Arc::new(tokio::sync::Semaphore::new(1)), + } + } + + /// Initialize a genuine /1 queue inside the fixture using the shared command path. + fn initialized_queue(fixture: &Fixture) { + let items = vec![json!({ + "key": "item-c1", "subject_id": "c1", "policy_key": "policy", + "author_keys": ["source-author"], + "assignments": [ + {"reviewer_key":"a-reviewer","role_key":"review"}, + {"reviewer_key":"b-reviewer","role_key":"review"} + ], "due_at": null + })]; + std::fs::write( + fixture.root().join("review-policy.json"), + serde_json::to_vec_pretty(&json!({ + "schema_version":"forge.review-init/1", "roles":[{"key":"review"}], + "reviewers":[ + {"key":"a-reviewer","role_keys":["review"]}, + {"key":"b-reviewer","role_keys":["review"]} + ], "policies":[{ + "key":"policy", "seats":[{"role_key":"review","count":2}], + "substitutions":[], "abstention_rule":"nonapproving", + "empty_abstention_reasons":[], "author_separation":"declared-keys" + }], "items":items + })) + .unwrap(), + ) + .unwrap(); + crate::review::commands::init( + &InitOptions { + project_root: fixture.root(), + sources: Path::new("locator.json"), + policy: Path::new("review-policy.json"), + queue_id: "55555555-5555-4555-8555-555555555555", + created_at: "2026-10-04T10:00:00Z", + output: Path::new("queue.json"), + }, + &mut NoopControl, + ) + .unwrap(); + std::fs::write(fixture.root().join("rationale.txt"), b"PRIVATE-REVIEW-RATIONALE").unwrap(); + } + + fn request_body(output: &str) -> Value { + json!({ + "family":"review", "queue":"queue.json", "rationale_file":"rationale.txt", + "item_key":"item-c1", "reviewer_key":"a-reviewer", "reviewer_role":"review", + "disposition":"approve", "responded_at":"2026-10-04T12:00:00Z", + "response_id":RESPONSE_ID, "output":output + }) + } + + /// S-1 round-trip: the route publishes the same portable response the CLI + /// `respond()` path produces, decodable by the closed review decoder. + #[test] + fn response_file_write_round_trips_through_shared_respond_path() { + let fixture = Fixture::new(false); + initialized_queue(&fixture); + let state = machine_state(Root::open(fixture.root()).unwrap(), false); + let response = write_response(&state, &request_body("response.json"), budget()).unwrap(); + assert_eq!(response.status(), 200); + let runtime = tokio::runtime::Builder::new_current_thread().build().unwrap(); + let bytes = runtime.block_on(response.into_body().collect()).unwrap().to_bytes(); + let body: Value = serde_json::from_slice(&bytes).unwrap(); + assert_eq!(body["output"], "response.json"); + assert_eq!(body["response_id"], RESPONSE_ID); + let raw = std::fs::read(fixture.root().join("response.json")).unwrap(); + let closed = + decode::decode_response(&raw, &mut ContractLedger::default(), &mut NoopControl) + .unwrap(); + let document = closed.document(); + assert_eq!(document.response_id, RESPONSE_ID); + assert_eq!(document.item_key, "item-c1"); + assert_eq!(document.queue_id, "55555555-5555-4555-8555-555555555555"); + // The private rationale round-trips into the response (it is a response + // field); exports, not the response file, are what redact it. + assert_eq!(document.rationale, "PRIVATE-REVIEW-RATIONALE"); + } + + /// Confinement refusal: absolute/traversal paths never reach the review capture. + #[test] + fn response_write_refuses_unconfined_paths() { + let fixture = Fixture::new(false); + initialized_queue(&fixture); + let state = machine_state(Root::open(fixture.root()).unwrap(), false); + for path in ["../escape.json", "/absolute.json", "a/../b.json", ".hidden.json"] { + let error = write_response(&state, &request_body(path), budget()).unwrap_err(); + assert_eq!(error.code, "resource-containment", "{path}"); + } + assert!(!fixture.root().join("response.json").exists()); + } + + /// Closed-contract refusal: a mismatched family/queue never publishes, and the + /// safe diagnostic carries no private rationale or parser prose. + #[test] + fn response_write_refuses_mismatched_family_without_leaking_prose() { + let fixture = Fixture::new(false); + initialized_queue(&fixture); + let state = machine_state(Root::open(fixture.root()).unwrap(), false); + let mut body = request_body("response.json"); + body["family"] = json!("lifecycle"); + let error = write_response(&state, &body, budget()).unwrap_err(); + assert_eq!(error.code, "review-response-refused"); + assert!(!error.message.contains("PRIVATE-REVIEW-RATIONALE")); + assert!(!fixture.root().join("response.json").exists()); + } + + /// No-replace publication: an existing destination is refused, never overwritten. + #[test] + fn response_write_refuses_existing_destination() { + let fixture = Fixture::new(false); + initialized_queue(&fixture); + std::fs::write(fixture.root().join("response.json"), b"ORIGINAL").unwrap(); + let state = machine_state(Root::open(fixture.root()).unwrap(), false); + let error = write_response(&state, &request_body("response.json"), budget()).unwrap_err(); + assert_eq!(error.code, "invalid-request"); + assert_eq!(std::fs::read(fixture.root().join("response.json")).unwrap(), b"ORIGINAL"); + } + + /// Read-only sessions never write a response file: the guard's mutation scope + /// check refuses before any project I/O, exactly as for other write routes. + #[test] + fn response_write_is_refused_in_read_only_session() { + let fixture = Fixture::new(false); + initialized_queue(&fixture); + let state = machine_state(Root::open(fixture.root()).unwrap(), true); + let token = state.session.lock().unwrap().machine_capability().unwrap(); + let error = state.session.lock().unwrap().authorize(&token, false, true).unwrap_err(); + assert_eq!(error.code, "read-only-session"); + assert!(!fixture.root().join("response.json").exists()); + } + + /// An invalid capability never authorizes the write; the guard refuses first. + #[test] + fn response_write_requires_a_valid_capability() { + let fixture = Fixture::new(false); + initialized_queue(&fixture); + let state = machine_state(Root::open(fixture.root()).unwrap(), false); + let error = + state.session.lock().unwrap().authorize(&"0".repeat(64), false, true).unwrap_err(); + assert_eq!(error.code, "unauthorized"); + assert!(!fixture.root().join("response.json").exists()); + } +} diff --git a/src/workspace/reports.rs b/src/workspace/reports.rs index 7fbd5bfd..f376c944 100644 --- a/src/workspace/reports.rs +++ b/src/workspace/reports.rs @@ -16,6 +16,10 @@ pub(crate) struct Report { pub(crate) kind: String, pub(crate) inputs: Vec, summary: Value, + /// M-13 opt-in source excerpts; absent unless explicitly requested. The + /// conservative default envelope omits this field and stays byte-identical. + #[serde(default, skip_serializing_if = "Option::is_none")] + excerpts: Option>, } #[derive(Serialize, Deserialize, PartialEq, Eq)] #[serde(deny_unknown_fields)] @@ -79,22 +83,37 @@ fn pins(snapshot: &Snapshot, kind: &str) -> Result> { Ok(pins) } +#[cfg(test)] pub(crate) fn render(snapshot: &Snapshot, kind: &str, summary: Value) -> Result> { + render_with_excerpts(snapshot, kind, summary, None) +} + +/// Render with optional M-13 opt-in source excerpts. Only an explicit sensitive +/// export passes `Some`; the default `None` envelope is byte-identical to today. +pub(crate) fn render_with_excerpts( + snapshot: &Snapshot, + kind: &str, + summary: Value, + excerpts: Option>, +) -> Result> { let report = Report { schema_version: "forge.workspace-report/1".into(), kind: kind.into(), inputs: pins(snapshot, kind)?, summary, + excerpts, }; report.validate()?; report.bytes() } impl Report { fn validate(&self) -> Result<()> { - contract::validate( - "WorkspaceReportEnvelope", - &serde_json::to_value(self).map_err(|_| Error::invalid())?, - )?; + let value = serde_json::to_value(self).map_err(|_| Error::invalid())?; + // The conservative default envelope stays on the frozen v1 contract; + // only an explicit M-13 opt-in carries excerpts, admitted by v2 alone. + let major = + if self.excerpts.is_some() { contract::ApiMajor::V2 } else { contract::ApiMajor::V1 }; + contract::validate_for(major, "WorkspaceReportEnvelope", &value)?; if self.schema_version != "forge.workspace-report/1" || self.inputs.len() > 100 { return Err(Error::invalid()); } @@ -107,6 +126,23 @@ impl Report { } last = &pin.resource_id; } + if let Some(excerpts) = &self.excerpts { + if self.kind != "trace" || excerpts.len() > 100 { + return Err(Error::invalid()); + } + for excerpt in excerpts { + let object = excerpt.as_object().ok_or_else(Error::invalid)?; + if object.len() != 5 + || object["element_id"].as_str().is_none_or(|s| s.is_empty() || s.len() > 200) + || object["source_file"].as_str().is_none_or(|s| s.is_empty() || s.len() > 512) + || object["source_line"].as_u64().is_none_or(|n| n == 0 || n > 1_000_000) + || object["text"].as_str().is_none_or(|s| s.len() > 500) + || object["truncated"].as_bool().is_none() + { + return Err(Error::invalid()); + } + } + } let keys: &[&str] = match self.kind.as_str() { "trace" => &[ "total_elements", @@ -171,9 +207,14 @@ impl Report { Ok(format!("{PREFIX}{escaped}{SUFFIX}").into_bytes()) } pub(crate) fn matches(&self, snapshot: &Snapshot) -> Result { + let excerpts_match = match &self.excerpts { + None => true, + Some(excerpts) => *excerpts == super::domain::trace_excerpts(snapshot)?, + }; Ok(self.inputs == pins(snapshot, &self.kind)? && self.kind == "trace" - && self.summary == super::domain::trace_counts(snapshot)?) + && self.summary == super::domain::trace_counts(snapshot)? + && excerpts_match) } } pub(crate) fn parse(bytes: &[u8]) -> Result { @@ -226,4 +267,89 @@ mod tests { let changed = String::from_utf8(bytes).unwrap().replace("", ""); assert!(parse(changed.as_bytes()).is_err()); } + + /// Build a snapshot with one traced catalog control resolving to a source line. + fn traced_snapshot() -> (tempfile::TempDir, Snapshot) { + let dir = tempfile::tempdir().unwrap(); + let ns = crate::oscal::trace_embedding::FORGE_TRACE_NS; + std::fs::write( + dir.path().join("policy.md"), + "# Policy\n\nStaff must review proposed changes.\n", + ) + .unwrap(); + let catalog = json!({"catalog":{ + "uuid":"11111111-1111-4111-8111-111111111111", + "metadata":{"title":"Synthetic catalog","last-modified":"2026-09-10T00:00:00Z","version":"1","oscal-version":"1.2.3"}, + "controls":[{"id":"control-a","title":"Synthetic control","props":[ + {"name":"source-file","ns":ns,"value":"policy.md"}, + {"name":"source-section","ns":ns,"value":"Policy"}, + {"name":"source-line","ns":ns,"value":"3"} + ]}] + }}); + std::fs::write(dir.path().join("catalog.json"), serde_json::to_vec(&catalog).unwrap()) + .unwrap(); + std::fs::write( + dir.path().join(super::super::index::INDEX_PATH), + serde_json::to_vec( + &json!({"schema_version":"forge.workspace/1","label":"M-13 fixture","resources":[ + {"key":"policy","role":"policy-source","path":"policy.md"}, + {"key":"catalog","role":"oscal-catalog-artifact","path":"catalog.json"} + ]}), + ) + .unwrap(), + ) + .unwrap(); + let root = super::super::root::Root::open(dir.path()).unwrap(); + let snapshot = Snapshot::capture(&root).unwrap(); + (dir, snapshot) + } + + /// M-13 default exports no sensitive content; the envelope is byte-identical + /// to the conservative render and carries no excerpts field. + #[test] + fn default_trace_export_has_no_excerpts_and_is_byte_identical() { + let (_dir, snapshot) = traced_snapshot(); + let summary = super::super::domain::trace_counts(&snapshot).unwrap(); + let default = render(&snapshot, "trace", summary.clone()).unwrap(); + let explicit_none = render_with_excerpts(&snapshot, "trace", summary, None).unwrap(); + assert_eq!(default, explicit_none); + let text = String::from_utf8(default).unwrap(); + assert!(!text.contains("excerpts")); + assert!(!text.contains("Staff must review proposed changes.")); + assert!(parse(&explicit_none).unwrap().matches(&snapshot).unwrap()); + } + + /// M-13 opt-in includes bounded source excerpts and still round-trips. + #[test] + fn opt_in_trace_export_includes_bounded_excerpts() { + let (_dir, snapshot) = traced_snapshot(); + let summary = super::super::domain::trace_counts(&snapshot).unwrap(); + let excerpts = super::super::domain::trace_excerpts(&snapshot).unwrap(); + assert_eq!(excerpts.len(), 1); + assert_eq!(excerpts[0]["text"], "Staff must review proposed changes."); + assert_eq!(excerpts[0]["source_line"], 3); + assert_eq!(excerpts[0]["truncated"], false); + let bytes = render_with_excerpts(&snapshot, "trace", summary, Some(excerpts)).unwrap(); + let text = String::from_utf8(bytes.clone()).unwrap(); + assert!(text.contains("Staff must review proposed changes.")); + let report = parse(&bytes).unwrap(); + assert!(report.matches(&snapshot).unwrap()); + // A default envelope must not match an opt-in snapshot's excerpt binding. + let default = + render(&snapshot, "trace", super::super::domain::trace_counts(&snapshot).unwrap()) + .unwrap(); + assert_ne!(default, bytes); + } + + /// Excerpts are trace-only and bounded; a non-trace report refuses them. + #[test] + fn excerpts_are_refused_for_non_trace_reports() { + let (_dir, snapshot) = traced_snapshot(); + let excerpt = json!({"element_id":"control-a","source_file":"policy.md","source_line":3,"text":"x","truncated":false}); + let summary = json!({"eligible_controls":0,"referenced_controls":0}); + assert!( + render_with_excerpts(&snapshot, "mapping-collection", summary, Some(vec![excerpt])) + .is_err() + ); + } } diff --git a/tests/api_contract_validation.rs b/tests/api_contract_validation.rs index a2ef8a8a..3f55c05d 100644 --- a/tests/api_contract_validation.rs +++ b/tests/api_contract_validation.rs @@ -1020,7 +1020,7 @@ mod s3_api2_contracts { let first = operations(&one); let second = operations(&two); assert_eq!(first.len(), 39); - assert_eq!(second.len(), 65); + assert_eq!(second.len(), 66); let mut left: Vec<_> = first .iter() .map(|operation| { @@ -1625,7 +1625,7 @@ fn release_inventory_contains_both_current_api_families() { let document = load_yaml_as_json(&repo_path(document_path)); assert_eq!(document["info"]["version"], version); let declared_operations = operations(&document); - assert_eq!(declared_operations.len(), if major == 1 { 39 } else { 65 }); + assert_eq!(declared_operations.len(), if major == 1 { 39 } else { 66 }); assert!( declared_operations .iter() From 5d0c5737db792f034a4a8e5277c775040606a7ca Mon Sep 17 00:00:00 2001 From: Brian Luby Date: Sat, 14 Nov 2026 14:52:47 -0800 Subject: [PATCH 2/2] fix(workspace): dispatch S-1 response writes on the documented v2 path CodeRabbit PR #290: the S-1 dispatcher matched the private canonical key unconditionally, so a v2 launch admitted /api/v2/review-queue/responses against the OpenAPI contract but never reached write_response, while the frozen v1 namespace kept an unintended alias. Gate the route on ApiMajor::V2 and the exact /api/v2/review-queue/responses wire path, mirroring the other v2 mutation routes; transport admission (loopback, exact-Host pin, write-scoped capability) and the handler's confinement fences are unchanged. Add a dispatch-level test: v2 POST publishes and round-trips the response, v1 is refused not-found. Capability matrix doc: current API2.4 draft total 65 -> 66 with CM-53 writeReviewResponse (matches the OpenAPI count and contract tests). --- docs/api/capability-matrix-v2.md | 2 +- src/workspace/http.rs | 17 +++++++++------ src/workspace/http_review.rs | 37 ++++++++++++++++++++++++++++++++ 3 files changed, 48 insertions(+), 8 deletions(-) diff --git a/docs/api/capability-matrix-v2.md b/docs/api/capability-matrix-v2.md index b954fe86..0c51741d 100644 --- a/docs/api/capability-matrix-v2.md +++ b/docs/api/capability-matrix-v2.md @@ -144,7 +144,7 @@ API 2.3.0 declares57 operations, preserving the51-operation2.2 contract and addi ## Staged source successor: API2.4 -The current draft contract declares eight staged-source operations (65 total) and five actions. API1/1.2.0 remains 39; the inline Bundle3/2.3 checkpoint remains 57. Staged controls require explicit 2.4; the maintained client admits 2.4 for inspection, metadata and inline-source features according to their separate version gates. These declarations do not establish a published release or acceptance; advertisement and conformance evidence must bind the selected runtime/artifact. +The current draft contract declares eight staged-source operations (66 total) and five actions. API1/1.2.0 remains 39; the inline Bundle3/2.3 checkpoint remains 57. Staged controls require explicit 2.4; the maintained client admits 2.4 for inspection, metadata and inline-source features according to their separate version gates. These declarations do not establish a published release or acceptance; advertisement and conformance evidence must bind the selected runtime/artifact. | ID | Action | Step | Stories | Operations | Authorization | |---|---|---|---|---|---| diff --git a/src/workspace/http.rs b/src/workspace/http.rs index c098c691..1f48a387 100644 --- a/src/workspace/http.rs +++ b/src/workspace/http.rs @@ -964,13 +964,6 @@ fn dispatch( state.stopped.store(true, Ordering::Release); return json_response(json!({"state":"shutting-down"}), "ShutdownResponse"); } - if method == "POST" && path == "/api/v1/review-queue/responses" { - return review::write_response( - state, - payload.as_ref().ok_or_else(Error::invalid)?, - read_deadline, - ); - } if state.api_major == ApiMajor::V2 && method == "GET" && let Some(route) = ReadQuery::route(path) @@ -990,6 +983,16 @@ fn dispatch( read_deadline, ); } + if state.api_major == ApiMajor::V2 + && method == "POST" + && wire_path == "/api/v2/review-queue/responses" + { + return review::write_response( + state, + payload.as_ref().ok_or_else(Error::invalid)?, + read_deadline, + ); + } if state.api_major == ApiMajor::V2 { if method == "POST" && path == "/api/v1/project/source-bundle-imports" { return source::import_response( diff --git a/src/workspace/http_review.rs b/src/workspace/http_review.rs index 19ceedf9..177a8d02 100644 --- a/src/workspace/http_review.rs +++ b/src/workspace/http_review.rs @@ -295,4 +295,41 @@ mod tests { assert_eq!(error.code, "unauthorized"); assert!(!fixture.root().join("response.json").exists()); } + + /// The documented v2 wire path reaches the shared handler through dispatch; + /// the frozen v1 namespace never admits the additive S-1 operation. + #[test] + fn response_write_dispatches_on_the_v2_wire_path_only() { + let fixture = Fixture::new(false); + initialized_queue(&fixture); + let state = Arc::new(machine_state(Root::open(fixture.root()).unwrap(), false)); + let bytes = serde_json::to_vec(&request_body("response.json")).unwrap(); + let response = super::super::dispatch( + &state, + "POST", + "/api/v2/review-queue/responses", + "", + None, + &bytes, + budget(), + ) + .unwrap(); + assert_eq!(response.status(), 200); + let raw = std::fs::read(fixture.root().join("response.json")).unwrap(); + let closed = + decode::decode_response(&raw, &mut ContractLedger::default(), &mut NoopControl) + .unwrap(); + assert_eq!(closed.document().response_id, RESPONSE_ID); + let error = super::super::dispatch( + &state, + "POST", + "/api/v1/review-queue/responses", + "", + None, + &bytes, + budget(), + ) + .unwrap_err(); + assert_eq!(error.code, "not-found"); + } }