Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion docs/api/capability-matrix-v2.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
Expand Down Expand Up @@ -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."
}
]
3 changes: 2 additions & 1 deletion docs/api/capability-matrix-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|---|---|---|---|
Expand All @@ -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 |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in bf7623e: "65 total" -> "66 total", verified against the OpenAPI doc (66 operations incl. writeReviewResponse) and contract tests (assert_eq!(second.len(), 66)). The 65s in compatibility.md/architecture.md are dated checkpoint records pinned to commit 304b31f (historical, correct as-is) — left untouched.


**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.

Expand Down
251 changes: 248 additions & 3 deletions docs/api/forge-workspace-v2.openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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"
},
Expand Down Expand Up @@ -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": [
Expand Down Expand Up @@ -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.",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": [
Expand Down
27 changes: 19 additions & 8 deletions src/cli/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,12 @@ pub enum Commands {
/// Composition provenance map used to resolve assembled lines to component instances
#[arg(long)]
composition_provenance: Option<PathBuf>,

/// 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
Expand Down Expand Up @@ -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(
Expand Down
Loading