feat(agent): make ingestion preparation reproducible

protocols/CONTRIBUTIONS.md

@@ -1,6 +1,6 @@
 # Contributions and run recovery
 
-Before a connected workflow, call `diagnostics` and verify that the required MCP tool names are present in the pinned `contracts/service-v1.json` inventory. Use each tool's schema advertised by MCP discovery for its arguments; consult only the relevant pinned contract entry if that schema is missing or differs. Do not read every record schema or the full contract during routine ingestion. Diagnostics reports the authenticated role, authorized projects/capabilities, explicit selected scope, source-transfer limits, service/catalog versions and canonical/index revisions without returning credentials or principal IDs. `connection_status=authenticated` proves only this call; `workflow_status=not_verified` means native workflow acceptance remains separate. If a required tool is absent or its input schema differs, stop before mutation and report the drift. `proposal_evaluate` is the deterministic preflight for one complete, real proposal. Never probe it with a placeholder payload, zero digest or guessed identity; never call `proposal_status` with a fabricated proposal ID. The service's `proposal_submit` response remains authoritative. Owner decisions use a separate owner transport and are not available to agents. Runs are agent-owned, explicitly scoped service records; they do not schedule work or grant capability.
+Before a connected workflow, call `diagnostics` and use MCP discovery to confirm the required tools and their advertised input schemas. The schemas discovered from the active server are authoritative for this session. Do not open `manifest.json`, `contracts/service-v1.json`, record schemas, the README or helper-script source just to verify tool availability, arguments or checkpoint behavior. If a required tool is absent or a discovered schema causes a concrete mismatch, stop before mutation and inspect only the relevant pinned contract entry; report the drift if that does not resolve it. Diagnostics reports the authenticated role, authorized projects/capabilities, explicit selected scope, source-transfer limits, service/catalog versions and canonical/index revisions without returning credentials or principal IDs. `connection_status=authenticated` proves only this call; `workflow_status=not_verified` means native workflow acceptance remains separate. `proposal_evaluate` is the deterministic preflight for one complete, real proposal. Never probe it with a placeholder payload, zero digest or guessed identity; never call `proposal_status` with a fabricated proposal ID. The service's `proposal_submit` response remains authoritative. Owner decisions use a separate owner transport and are not available to agents. Runs are agent-owned, explicitly scoped service records; they do not schedule work or grant capability.
 
 ## Build attributable proposals
 
@@ -14,21 +14,29 @@ Every source registration affects both the shared-source policy and each project
 
 Before creating a new node, search the explicit project and shared scope with multiple lexical queries: the proposed title, distinctive terms, aliases and likely synonyms. Inspect plausible matches with `get_node`. If the finding belongs to an existing node, preserve its stable ID and supported content when proposing an evidence-backed update; do not create a second node for the same concept. Keep materially different populations, time periods, settings, mechanisms or conclusions distinct. Similarity is only a review cue. The backend flags exact entity name/alias matches but does not detect duplicate notes, cases, concepts or datapoints; if likely duplicates remain unresolved after search, submit a non-blocking review flag and do not create another node yet.
 
-Finalize claim text and evidence before creating support assessments or digests. Every evidence `assertion_path` must name its exact typed claim field (`claims[n].text`, `assumptions[n].text` or `limitations[n].text`). Its `assertion_digest` must bind to that exact claim text. Set the assessment's `assertion_digest` to the same value and `evidence_digests` to the digests of the claim's final evidence objects. Any edit to claim text or evidence requires regenerating those dependent values and the proposal `payload_digest` before `proposal_evaluate`.
+Finalize claim text, evidence and locators, then call the read-only `proposal_prepare` MCP tool with the complete draft proposal. It fills each claim's exact typed `assertion_path`, assertion digest, evidence digests and final payload digest, and returns prepared `proposal_json`. Use that JSON unchanged for `proposal_evaluate`; after any edit, call `proposal_prepare` again. It does not evaluate, store or submit the proposal. Do not run shell commands or manually hash proposal content. If `proposal_prepare` is unavailable, stop before evaluation and report that deterministic digest preparation is missing.
 
-Use the canonical GEWU digest rules, not a hash of the raw quote or raw request text. Canonical JSON is UTF-8 JSON with Unicode preserved, sorted keys, no insignificant whitespace and no NaN values. The assertion digest is SHA-256 of canonical JSON `{"assertion": normalized_text}`, where text has CRLF and CR converted to LF and is normalized to Unicode NFC. An evidence digest is SHA-256 of canonical JSON for the complete evidence object in schema JSON form. The assessment's `evidence_digests` must match those final evidence digests. The proposal payload digest is SHA-256 of canonical JSON for the final operations serialized as GEWU v1 contract records. Recompute it after adding/removing/changing any operation. If the client cannot reproduce these rules, stop before submission and report that digest generation is unavailable.
+`proposal_prepare` applies the canonical GEWU digest rules: UTF-8 canonical JSON, Unicode preserved, sorted keys, no insignificant whitespace and no NaN values. It binds assertions to normalized exact claim text, hashes complete evidence objects and hashes the final typed operations. Its server result is authoritative for dependent digest fields.
+
+The proposal envelope must include `schema_version`, `proposal_id`, `revision`, `initiating_project_id`, `scope`, `base_commit`, `payload_digest`, `proposer_id`, `run_id` and `operations`. `proposal_prepare` fills dependent digests; it does not invent the run, scope, principal, base revision or proposal metadata. Do not add unsupported envelope fields such as `created_at` or `reason`. For a PDF citation, use `locator.kind="pdf_page_span"` and the page from the extraction block; `text_span` is for non-PDF text and cannot include a page. Do not call `proposal_evaluate` unless `proposal_prepare` returns `status="prepared"`; evaluate only its returned `proposal_json` unchanged. If preparation returns `status="invalid"`, correct the named issue and retry once. Never probe preparation with `{}` or another incomplete draft.
+
+A claim's `assessment` uses the GEWU fields `assessment_id`, `assertion_digest`, `evidence_digests`, `assessor_id`, `run_id`, `method`, `status` and `rationale`. Do not add guessed fields such as `support_level`, `confidence` or `assessed_at`; `proposal_prepare` reports typed validation issues but does not translate another schema.
 
 `list_projects` exposes authorized IDs, and `get_project_context` returns the selected authorized project's north star, key questions, watch list, taxonomy extensions, research lenses and explicitly saved ingest guidance without exposing its autonomy policy. Projects default to technical, conceptual, cultural-historical and financial-market lenses. These are coverage prompts, not quotas. Use this context for ingest/curation; keep objective and scope explicit and never infer authority from a folder or project name.
 
 When available, `ingest_review_create` stores a source-bound review flag. Submit it after or alongside normal proposal processing, never as a reason to wait on human review before evaluating/submitting plausible findings. Bind it to the durable run and an extraction owned by the submitting agent and granted project; the exact excerpt and locator must match the staged extraction. A queue entry is a notification/filter and feedback record, not a proposal, source registration, acceptance result or publication. Human reviewers may confirm relevance, mark it irrelevant or defer feedback. Reusable project guidance is added to future context only when a human explicitly saves a rule. If the review operation is absent, preserve and report plausible uncertain material rather than silently deferring it.
 
+The `ingest_review_create` MCP tool takes one `review_json` string, not review fields as top-level tool arguments. Its request requires `review_id`, `project_id`, `run_id`, `source_revision_id`, `extraction_id`, `locator`, `excerpt`, `lens`, `summary` and `relevance_rationale`; use `candidate_facet_labels` for defined label candidates. The field is `relevance_rationale`, not `reason`. A call invokes advisory Jev relevance/lens and facet judgments when configured and returns any `jev_facet_resolutions`; it is not a prerequisite for ordinary proposal acceptance. Use this call when a label needs explicit Jev normalization or human categorization review, and treat its saved item as a non-blocking notification.
+
 Current capability gaps that must be reported when relevant: retrieval is lexical only; URL capture requires an exact operator-allowlisted public host. URL and selected-file intake support UTF-8 text/Markdown/HTML and PDF; selected `.vtt` and `.srt` files are parsed into timestamped cues and tagged `capture_method=transcript`. Transcript evidence must cite the exact text span and matching cue start/end milliseconds. `source_capture_text` accepts explicitly supplied UTF-8 plain text or Markdown up to 1 MB. It requires a stable capture ID, stores the completed metadata candidate in a private bounded receipt journal, returns the same candidate for an exact retry, and conflicts if the same ID is reused with changed inputs. Source records distinguish URL fetch, local-file, transcript, declared NotebookLM-export and pasted-text capture methods; the NotebookLM label does not verify export provenance. HTML citations refer to the visible-text extraction, not markup-byte offsets. PDF extraction is qualified only on Linux in a sandbox; scanned PDFs return `PDF_NO_TEXT`. Failed URL captures can be registered as artifact-free references, and source records include publisher, author, publication date, license and reliability fields. supplied NotebookLM exports, Windows/macOS PDF extraction, native host workflows and real-source location checks remain unqualified. There are no vector/hybrid search or project-export/import operations. Duplicate review can nominate exact entity name/alias matches only within the caller-readable explicit scope; it does not merge records. Reversible merge, protected owner decisions, promotion and synthesis-dependency warnings remain unavailable. Do not describe these as implemented merely because a pipeline or record schema can represent related data.
 
 Use read tools for retrieval and typed MCP proposals for contributions. Source upload completion establishes a staged artifact, not an accepted source. Treat policy acceptance and index visibility as separate outcomes. Corrections append revisions; accepted records are corrected through new linked proposals.
 
 Create the service run with `run_create` before capture or proposal submission. Persist returned run identity and operation input digests in the private local checkpoint, then append service checkpoints with `run_checkpoint`; `run_status` is authoritative after uncertain calls and returns the latest revision. Each update uses `expected_revision`; retry the same checkpoint unchanged after uncertainty. The local helper remains a private host-side recovery mirror and is useful when offline. Checkpoints include pack/skill/pipeline versions and hashes, explicit project/shared scope and lens, source/extraction references, stage, output hashes, included/excluded/skipped coverage, pending side effects and last receipt. The helper rejects credential/source-body fields and verifies pinned module hashes on resume. The pack does not provide a host scheduler.
 
-Use the checkpoint contract in the [pack README](../README.md) and resolve the module registry in the manifest. Record its snapshot digest and every applicable module's contract ID/version and file hash, including the profile and shared protocols. Verify those hashes before resuming; a mismatch requires the original snapshot or an explicitly revalidated successor run.
+Create the service run immediately after diagnostics, project context and explicit scope, before source transfer or proposal work. `run_create` takes `request_json`; supply a JSON object with `run_id`, `objective`, `scope`, `lens`, `pack_id`, `pack_version`, `pack_snapshot_digest` and `module_pins`. Use the compact `run_pins` object in `.agents/gewu-install.json` for the four pack fields; the installer writes the required `module_id`, `implementation_version` and `sha256` for every module there. Do not inspect the manifest, run schemas or helper implementation to reconstruct these values. If `run_pins` is absent, inspect only the manifest's pack identifiers, snapshot digest and module entries. Persist the returned run identity and operation input digests in the private local checkpoint after the service run exists, then append service checkpoints with `run_checkpoint`; `run_status` is authoritative after uncertain calls and returns the latest revision. Each update uses `expected_revision`; retry the same checkpoint unchanged after uncertainty. The `sources` field is an array of objects with `source_revision_id` and `status` (`selected`, `captured`, `extracted`, `unavailable` or `failed`); include `artifact_sha256` and `extraction_id` when known. Do not store source revision IDs as bare strings. Checkpoints include explicit project/shared scope and lens, stage, output hashes, included/excluded/skipped coverage, pending side effects and last receipt. The helper rejects credential/source-body fields and verifies pinned module hashes on resume. The pack does not provide a host scheduler.
+
+Both `run_create` and `run_checkpoint` take one `request_json` string containing their complete request object. A checkpoint object must include `run_id` and the exact current `expected_revision` from `run_status`, plus `stage`; include source references as objects and a coverage object. Do not send checkpoint fields as top-level MCP arguments or omit the run identity/revision. Update local checkpoint files only through the host's approved file tools; if those tools are unavailable, the service checkpoint is authoritative and must still be recorded.
 
 When upload completion is uncertain, call `source_upload_status` with the saved upload ID and resume only from its verified offsets. When proposal submission is uncertain, call `proposal_status` with the same proposal ID and revision. If accepted, reuse the returned receipt and do not resubmit. If evaluated but not accepted, inspect findings; if withdrawn, that proposal revision cannot be submitted. Never generate a fresh proposal ID to hide network uncertainty. Resume from preserved artifacts and service receipts; changed content requires a new proposal revision. Do not rerun a model and assume it reproduces the same output.