# Proposal Artifact Substrate v1 **Status:** Proposed planning substrate **Scope:** Workbench / teaching / proposal artifacts / future CORE-Logos Studio **Branch:** `docs/proposal-artifact-substrate-v1` **No ADR number assigned in this document.** This is a consolidation plan and implementation brief. A numbered ADR may ratify it later if the design survives review. --- ## Purpose CORE has reached the point where `proposal` cannot remain a page-specific idea or a math-specific workflow. Proposal artifacts are the system's lawful bridge between: ```text engine observation → structured hypothesis → evidence-bearing proposed change → operator review → ratified mutation, if and only if an admitted handler exists → deterministic replay / audit reconstruction ``` The current implementation has one deep corridor — math proposals — and one shallower corridor — cognition teaching proposals. CORE-Logos / pack proposals are not yet forged through this substrate at all. That split was historically reasonable: math had ratification handlers that were already proven and narrowly admitted by ADR-0173. But keeping separate proposal pipelines would now create architectural drift. This document defines the next substrate: one universal `ProposalArtifact` envelope, with subject-specific adapters and subject-specific validators, while preserving every existing trust boundary. The goal is not to grant new mutation power. The goal is to make every proposed change pass through the same evidence, validation, safety, replay, handler, and audit spine. --- ## Governing constraints read before this plan This plan is constrained by the following prior doctrine. ### CORE pillars and runtime invariants From `README.md` and `CLAUDE.md`: - CORE is a deterministic cognitive field system, not a transformer wrapper or generic chatbot. - The field invariant remains load-bearing: `versor_condition(F) < 1e-6` / `||F * reverse(F) - 1||_F < 1e-6`. - Coherence is constructed, not monitored and repaired. - Mechanical Sympathy, Semantic Rigor, and Third Door remain the design filter. - Learning must be reviewed and auditable. - Pack mutation is proposal-only until reviewed. - No parallel correction or learning path. - If a visualization is load-bearing, the underlying data must first exist as deterministic JSON/JSONL/Markdown. - Any path touching packs, logs, dynamic imports, or filesystem paths must state its trust boundary. ### ADR-0160 — Workbench v1 - Workbench is an operator/auditor interface, not a chat clone. - It must answer: what happened, why allowed, what evidence supports it, can it replay, did it mutate anything, who/what ratifies next. - V1 is read-only by default. - Proposal before mutation and replay before persuasion are product doctrine. - Mutating proposals, corpus, packs, workflows, or engine state requires a later ADR and explicit gates. ### ADR-0161 — HITL async queue - The HITL queue is a deterministic projection over append-only sources, not a new persistence substrate. - Queue identity is `proposal_id`. - Pending proposals never become active truth. - There are no proposal-on-proposal dependencies. - CI may stage artifacts and open PRs but may not ratify. - Pack mutation queue remains out of scope in ADR-0161. ### ADR-0162 — Workbench design system - Design is a trust surface, not styling. - Stable JSON viewing must be deterministic, lossless, copyable, diffable, and large-document safe. - Empty/error/loading states must name next action, mutation status, reproducer, and safe retry semantics. - No animated cognition theater, no dashboard soup, no color-only state encoding. - Proposal queue and ratification components must preserve auditability and keyboard-first operation. ### ADR-0172 — math corpus decomposition mechanism - Proposal artifacts must carry structured reasoning traces. - Operators review the trace, not a black-box conclusion. - Reasoning traces are content-addressable and replayable. - Tier 2 proposals must include self-test evidence before HITL review. - Operator verdicts are future teaching signals; rejection/refinement rationale is part of the learning loop. ### ADR-0173 — Workbench ratification trust boundary - The Workbench is a local keyboard accelerator over existing local ratification handlers. - It is not a fourth ratification surface and not a new trust boundary. - Existing admitted handlers may be driven by `POST /math-proposals/{id}/ratify` only because they already preserve the same evidence, preconditions, exceptions, and append-only JSONL effects as CLI/Python entrypoints. - The amendment is narrow. It does not admit new mutation paths, new corpora, new pack types, remote operator auth, or unproven handlers. - No auto-ratify. No batch ratification in v1. No bypass of handler preconditions. ### ADR-0015 — CORE-Logos language packs - A language pack is not a dataset or translation table. - It is a deterministic, checksummed, compiled linguistic manifold. - Pack contents include manifest, lexicon, morphology, grammar attractors, cross-language resonance edges, and holonomy alignment cases. - OOV policy, ordering, morphology, alignment, and holonomy proof cases are load-bearing. - Unknown depth-language surfaces must not silently collapse to fallback points. --- ## Problem statement The Workbench currently exposes proposal artifacts unevenly: ```text math proposals → deep artifact record + UI detail + ratification corridor cognition proposals → queue projection + replay/provenance inspection + CLI fallback CORE-Logos packs → manifest/checksum inspection only, no proposal forge future modalities → no proposal path yet ``` This split is a historical implementation sequence, not the desired architecture. The risk is that each subject grows its own lifecycle: ```text math proposal lifecycle cognition proposal lifecycle pack proposal lifecycle vision proposal lifecycle ``` That would violate the Workbench's evidence-manifold direction and eventually create contradictory semantics for state, review, safety, replay, and ratification. The correct shape is: ```text one universal proposal artifact lifecycle + subject-specific proposal payloads + subject-specific validators + subject-specific handlers + one Workbench review language ``` --- ## Decision Introduce a universal `ProposalArtifact` substrate as the single Workbench-facing envelope for all proposed changes. The envelope standardizes identity, subject, evidence, reasoning, validation, affected artifacts, safety checks, handler routing, ratification status, and audit references. The envelope does **not** standardize the domain payload itself. Math, cognition, CORE-Logos, vision, audio, and future subjects may each define typed payloads and validation reports. What is universal is the review spine. --- ## Core distinction: proposal artifact vs ratification handler A proposal artifact is an evidence-bearing candidate for review. A ratification handler is a pre-admitted local mutation path that can apply a candidate after all preconditions pass. These must remain separate. ```text ProposalArtifact exists → reviewable ProposalArtifact validates → still not applied ProposalArtifact routes to admitted handler → apply may be enabled No admitted handler → proposal-only / CLI fallback / future ADR required ``` This distinction is the core safety boundary for CORE-Logos. A browser may help draft a Logos proposal before a handler exists. It must not apply that proposal until an admitted handler exists and tests prove the same invariants as the CLI path. --- ## Universal proposal envelope The implementation should converge toward this shape. Field names may be refined during implementation, but the sections are load-bearing. ```text ProposalArtifact: proposal_id: str schema_version: str subject: ProposalSubject state: pending | accepted | rejected | withdrawn | deferred | unknown capability_level: inspect_only | proposal_only | ratification_enabled source: ProposalSource proposed_change: ProposedChange reasoning_trace: ReasoningTrace | None evidence_pointers: tuple[EvidencePointer, ...] validation: ValidationReport | None replay_evidence: ReplayEvidence | None safety_report: SafetyReport | None affected_artifacts: tuple[AffectedArtifact, ...] checksum_impacts: tuple[ChecksumImpact, ...] handler_route: HandlerRoute | None suggested_cli: str | None audit_refs: tuple[AuditRef, ...] ui_disclosure: ProposalDisclosure ``` ### `ProposalSubject` ```text ProposalSubject: kind: math | cognition | logos_pack | pack | vision | audio | sensorimotor | runtime_policy | unknown subject_id: str partition: str display_name: str ``` Examples: ```text math / shape_category=multi_quantity_composition cognition / TeachingChainProposal logos_pack / he_logos_micro_v1 / alignment_edge_add logos_pack / grc_logos_micro_v1 / holonomy_case_add ``` ### `capability_level` This field prevents the UI from implying authority it does not have. | Level | Meaning | UI may do | |---|---|---| | `inspect_only` | Artifact can be inspected but not changed from Workbench. | Read, copy evidence, navigate, show CLI fallback. | | `proposal_only` | Workbench may draft or preview a proposal artifact, but cannot apply it. | Structured editor, validation preview, patch preview, export/copy CLI. | | `ratification_enabled` | A handler exists and was admitted by ADR/tests. | Enable ratify/reject/defer controls subject to preconditions. | No route may render a `Ratify` affordance unless `capability_level == ratification_enabled` and `handler_route` is present and admitted. ### `ProposedChange` ```text ProposedChange: change_kind: str payload: object payload_digest: str human_summary: str ``` This keeps payload type open while making the envelope hashable and inspectable. ### `EvidencePointer` ```text EvidencePointer: pointer_id: str evidence_hash: str | None source_path: str | None json_pointer: str | None trace_hash: str | None description: str | None ``` Evidence may point to audit rows, eval cases, refusal records, trace rows, pack entries, alignment edges, holonomy cases, or prior proposal verdicts. ### `ReasoningTrace` Reuse ADR-0172's concept: a stable sequence of typed reasoning steps. ```text ReasoningTrace: trace_id: str steps: tuple[ReasoningStep, ...] ``` The Workbench reviews the trace and the evidence, not merely the conclusion. ### `ValidationReport` ```text ValidationReport: validator_id: str verdict: pass | warning | fail | not_run checks: tuple[ValidationCheck, ...] ``` Subject adapters define checks, but the envelope provides a uniform report surface. ### `SafetyReport` ```text SafetyReport: verdict: clear | warning | failed | unknown wrong_zero_risk: none | bounded | live | unknown mutation_boundary: none | proposal_only | admitted_handler | forbidden checks: tuple[SafetyCheck, ...] ``` This is the field that prevents proposal UI from becoming persuasion theater. ### `AffectedArtifact` ```text AffectedArtifact: path: str artifact_kind: str before_digest: str | None after_digest: str | None mutation_mode: proposal_only | append_only | replace | unknown ``` For proposal-only flows, `after_digest` may be predicted, not applied. The UI must label predicted digests as predicted. ### `ChecksumImpact` ```text ChecksumImpact: manifest_path: str | None field: str before: str | None after: str | None status: unchanged | predicted | applied | not_applicable ``` ### `HandlerRoute` ```text HandlerRoute: handler_id: str admitted_by: str route: str required_preconditions: tuple[str, ...] dry_run_supported: bool ``` No `HandlerRoute` means no Workbench ratification. --- ## Universal lifecycle Every proposal artifact moves through the same conceptual phases. ```text drafted → validated → replayed_or_checked → safety_reviewed → routed_or_blocked → operator_decision → audit_recorded → replay_reconstructible ``` The stored state alphabet may remain ADR-0057-compatible where required. The Workbench can render additional transient UI dispositions, but durable state must not silently widen without a ratifying ADR. ### Drafted A candidate exists. It may come from the engine, CLI, Workbench forge, a demo, or a future modality compiler. ### Validated Subject-specific validators run. This may be syntax/schema validation, replay equivalence, pack checksum verification, morphology-link verification, holonomy proof status, or eval impact analysis. ### Replayed or checked Not every subject has turn replay. The universal phase is evidence re-checking: - math: replay equivalence / wrong=0 gate / two-arm confirmation - cognition: teaching-chain replay equivalence - CORE-Logos: pack compile/verify, morphology links, alignment targets, holonomy cases, checksum impacts - modalities: deterministic compiler replay / content-addressed delta replay ### Safety reviewed Safety report names mutation boundary, wrong=0 risk, partition risk, path safety, checksum risk, OOV/gate risk, and any missing proof obligations. ### Routed or blocked If an admitted handler exists, the proposal may show a ratification corridor. If not, the proposal remains proposal-only with a CLI/export/follow-up path. ### Operator decision Operator may ratify, reject, defer, withdraw, or refine depending on admitted state machine for the subject. This document does not widen durable state by itself. ### Audit recorded Every action that crosses a mutation boundary emits audit/telemetry per ADR-0173. Proposal-only draft creation should also be recordable once the substrate is implemented, but it must be labeled as non-mutating. ### Replay reconstructible Given the artifact sources and proposal logs, the Workbench projection must be reconstructible without hidden UI state. --- ## Subject adapters The universal envelope is consumed through adapters. Each adapter names source files, validators, safety checks, handler status, and UI affordances. ### Math adapter Current maturity: `ratification_enabled` for admitted claim classes. Sources: - `teaching/math_proposals/proposals.jsonl` - ratified math lexicon/frame/composition artifacts - eval/audit reports Existing strengths: - self-contained JSONL proposal records - evidence pointers - reasoning trace steps - wrong=0 assertion - replay equivalence hash - handler dispatch for LexicalClaim, FrameClaim, CompositionClaim - Workbench ratify/reject/defer UI Required migration: - wrap existing `MathProposalDetail` into `ProposalArtifact` - retain existing routes for compatibility during migration - expose `capability_level=ratification_enabled` only for admitted handlers - populate `affected_artifacts` and `checksum_impacts` after handler dry-run or predicted receipt support exists - connect audit events back into proposal timeline No behavior change in the migration PR. The first math adapter PR should be read-model-only. ### Cognition adapter Current maturity: `inspect_only`, moving to `ratification_enabled` only after Surface C parity is proven. Sources: - `teaching/proposals/proposals.jsonl` - contemplation reports - replay evidence - operator transition records Required work: - wrap `ProposalDetail` into `ProposalArtifact` - populate artifact references instead of returning empty `artifact_refs` - add review history / timeline projection - prove Surface C parity before enabling Workbench ratification - preserve ADR-0057 / ADR-0161 state reconstruction ### CORE-Logos adapter Current maturity: no proposal forge yet. Target next state: `proposal_only` first, not ratification-enabled. Sources: - `language_packs/data//manifest.json` - `lexicon.jsonl` - `glosses.jsonl` - morphology files - `alignment.jsonl` - frame/composition files when present - holonomy proof cases - pack validators / compiler checks Initial change kinds: ```text lexicon_add lexicon_update lexicon_remove gloss_add gloss_update morphology_add morphology_update alignment_edge_add alignment_edge_update holonomy_case_add holonomy_case_update frame_add composition_add ``` Initial UI capability: ```text structured proposal drafting schema validation safety report checksum impact prediction patch preview suggested CLI / PR instructions no apply button ``` Handler admission comes later, one handler family at a time. Required safety checks: - safe pack ID - manifest present - declared source file present - checksum matches or predicted checksum is clearly labeled - OOV policy valid for role - depth pack fail-closed when gate engaged - no dangling morphology links - no invalid alignment targets - no holonomy case with missing refs - epistemic-status distribution visible - known gaps carried forward - no silent promotion from speculative to coherent ### General pack adapter The broader `packs` route may remain an inventory view. Any pack mutation or patching path should reuse the CORE-Logos adapter where applicable and the universal proposal envelope always. ### Future modality adapters Audio, vision, environment, and sensorimotor proposal artifacts must enter through the same envelope. Because these substrates are gated and often afferent-only, initial capability should usually be `inspect_only` or `proposal_only`. No modality adapter may imply decode, actuation, or motor authority unless the governing ADR admits it. --- ## Workbench UX substrate The Workbench should render proposal artifacts through shared components rather than per-domain bespoke pages. ### Shared components ```text ProposalArtifactHeader ProposalSubjectBadge CapabilityLevelBadge ProposalEvidenceRail ReasoningTraceViewer ValidationReportPanel SafetyReportPanel AffectedArtifactsPanel ChecksumImpactPanel HandlerRoutePanel RatificationCorridor ProposalTimeline SuggestedCliPanel PatchPreviewPanel ``` ### Design rules - Every proposal screen names mutation status. - Every disabled ratification affordance names the failed precondition. - Every unknown or missing proof renders as unknown/missing, not as green. - Draft/preview/predicted/applied must be visibly distinct in text, not color only. - `StableJsonViewer` remains the raw artifact trust surface. - No auto-ratify, no batch ratification, no hidden background jobs. - No direct pack editing UI. - No route-specific proposal semantics that contradict the shared envelope. --- ## Backend API direction The future API should converge toward generic proposal endpoints while preserving old endpoints during migration. Read-only / projection: ```text GET /proposal-artifacts GET /proposal-artifacts/{proposal_id} GET /proposal-artifacts/{proposal_id}/timeline GET /proposal-artifacts/{proposal_id}/artifacts ``` Subject-specific draft endpoints may exist when they do not mutate substrate artifacts: ```text POST /logos/packs/{pack_id}/proposals/draft POST /proposal-artifacts/{proposal_id}/validate ``` Ratification remains subject to admitted handler routes: ```text POST /proposal-artifacts/{proposal_id}/ratify ``` But this generic route must refuse unless `handler_route` is admitted for the proposal subject and all preconditions pass. The route may initially be omitted entirely until generic routing is proven. During migration, existing math routes remain valid: ```text GET /math-proposals GET /math-proposals/{id} POST /math-proposals/{id}/ratify POST /math-proposals/{id}/reject POST /math-proposals/{id}/defer ``` The adapter layer can translate those into the universal envelope without changing behavior. --- ## Trust boundary matrix | Subject | Initial capability | May draft in UI? | May apply in UI? | Gate to enable apply | |---|---:|---:|---:|---| | Math / admitted handlers | `ratification_enabled` | No new drafting in this slice | Yes, existing narrow path | Existing ADR-0173 + handler tests | | Math / unsupported change kind | `proposal_only` or `inspect_only` | Later | No | New handler ADR/tests | | Cognition teaching proposal | `inspect_only` | No | Not yet | Surface C parity tests + implementation | | CORE-Logos pack proposal | `proposal_only` | Yes, after forge PR | No | New handler family ADR/tests | | General pack mutation | `proposal_only` | Later | No | Reviewed handler path | | Vision/audio modality proposal | `inspect_only` first | Later | No | Dedicated modality ADR/tests | | Runtime policy / identity | `inspect_only` unless separately ratified | No by default | No | Dedicated governance ADR | --- ## Implementation sequence ### S0 — This plan Create this document. No code. No schema changes. No mutation path. ### S1 — Universal envelope schemas, read-only only Add Python and TypeScript read-model schemas for `ProposalArtifact`, `ProposalSubject`, `SafetyReport`, `ValidationReport`, `AffectedArtifact`, `ChecksumImpact`, and `HandlerRoute`. No endpoints apply anything. Acceptance: - schema drift tests cover TS/Python mirrors - no new mutation routes - existing math/cognition endpoints unchanged ### S2 — Proposal artifact projection endpoint Add a read-only endpoint that projects existing math and cognition proposals into the universal envelope. ```text GET /proposal-artifacts GET /proposal-artifacts/{id} ``` Acceptance: - math proposal count matches `/math-proposals` - cognition proposal count matches `/proposals` - unsupported handlers render `capability_level != ratification_enabled` - missing artifacts render absence explicitly ### S3 — Shared UI components Build the shared proposal artifact components and render them behind a feature flag or route-internal experiment. Acceptance: - no existing ProposalsRoute behavior removed - every component has empty/error/loading state where applicable - no color-only status - keyboard focus works - raw JSON still available ### S4 — Math adapter migration Render math proposals through the universal proposal artifact components while preserving existing ratification behavior. Acceptance: - existing math ratify/reject/defer tests still pass - `RatificationCorridor` remains gated by pending + replay equivalent + admitted handler - no unsupported handler becomes enabled - target path/evidence hash after apply is surfaced in timeline or result panel ### S5 — Cognition adapter depth Populate artifact refs, review history, and proposal timeline for cognition proposals. Do not enable Workbench ratification until Surface C parity is proven. Acceptance: - artifact_refs no longer always empty when source artifacts exist - review_history is visible - CLI fallback remains available - Workbench ratify button absent or disabled with clear reason ### S6 — CORE-Logos proposal forge, proposal-only Add proposal-only drafting for CORE-Logos changes. Acceptance: - structured editor produces proposal artifact only - no language pack file is mutated - safety report includes pack-specific checks - checksum impacts are predicted and labeled predicted - patch preview is visible - suggested CLI/PR instructions are visible - no `Ratify` affordance exists ### S7 — CORE-Logos handler families, one at a time Admit one handler family per ADR/brief/PR sequence. Suggested order: 1. `gloss_add` / `gloss_update` 2. `lexicon_add` with speculative status only 3. morphology link attach/update 4. alignment edge add/update 5. holonomy case add/update 6. coherent/admissible status promotion only after a stricter review path exists Each family must prove: - append-only or deterministic file rewrite discipline - checksum update correctness - pack compile/verify pass - no depth-language OOV collapse - no silent epistemic promotion - rollback/replay reconstruction - audit event emission --- ## Acceptance gates for this substrate This substrate is ready to implement when reviewers agree the following are true: 1. The universal envelope does not widen durable proposal state without ADR review. 2. The universal envelope does not grant new mutation authority. 3. Math remains behavior-identical after adapter projection. 4. Cognition remains inspect-only until Surface C parity tests exist. 5. CORE-Logos begins proposal-only, not ratification-enabled. 6. Every proposal artifact can name evidence, validation, safety, affected artifacts, and handler status. 7. Missing evidence renders as missing, not as success. 8. Every route using the substrate preserves ADR-0162 empty/error/loading doctrine. 9. Every mutation-capable route names the handler, preconditions, target artifact, audit event, and replay boundary. 10. No UI path can apply a subject whose handler is not admitted. --- ## Explicit no-go list - No direct pack editor. - No generic `apply_patch` endpoint. - No browser write to `language_packs/data/*`. - No ratification affordance for proposal-only subjects. - No auto-ratify. - No batch ratification. - No hidden background validation that changes files. - No new durable proposal state names without ADR review. - No pack checksum rewrite from UI until a handler family admits it. - No using `ratifier_kind` as permission logic. - No treating Workbench as remote operator auth. - No proposal-on-proposal dependency chain. - No visualization as proof without deterministic underlying artifact. --- ## CORE-Logos implication CORE-Logos Studio should be the first major consumer after math/cognition are projected into the envelope. The Studio should not create a separate Logos proposal system. It should create Logos proposal artifacts using this universal envelope: ```text CORE-Logos proposed change → subject = logos_pack → change_kind = lexicon_add | morphology_add | alignment_edge_add | holonomy_case_add | ... → evidence pointers → safety report → checksum impact → patch preview → handler route absent → capability_level = proposal_only ``` Only after a specific Logos handler family is admitted may that family become `ratification_enabled`. This keeps CORE-Logos functional for active engineering and development while preserving the safety boundary that made math ratification lawful. --- ## Open questions 1. Should universal `deferred` be a durable state, or remain a Workbench UI disposition backed by existing state/log semantics? 2. Should proposal draft artifacts live under a new `proposal_artifacts/` tree, or remain subject-owned until ratified? 3. Should `POST /proposal-artifacts/{id}/validate` be read-only by contract, or should validation always be a fresh read endpoint with query parameters? 4. What is the smallest CORE-Logos handler family safe enough to ratify first: gloss updates, lexicon additions as speculative, or holonomy case additions? 5. Should operator rejection/refinement attach to reasoning-trace step IDs universally, not just math Tier 2? None of these open questions block S1/S2 read-only projection. --- ## Final design sentence A proposal artifact is CORE's lawful way to say: > “The engine has seen enough to suggest a change, but not enough to become the change.” The Workbench's job is to make that distinction impossible to miss.