From 3d7a742fa19af35ea25519337897de55b37d9c53 Mon Sep 17 00:00:00 2001 From: Dylan Roy <249851642+d6g8k5htny-coder@users.noreply.github.com> Date: Fri, 23 Oct 2026 06:22:25 -0500 Subject: [PATCH 1/2] docs: GB-5 proposal for v2 node_id <-> artifact_path+sha binding (doc only) --- .../2026-10-08-artifact-index-contract.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/plans/2026-10-08-artifact-index-contract.md b/docs/plans/2026-10-08-artifact-index-contract.md index 09788a526..ffd1b1de3 100644 --- a/docs/plans/2026-10-08-artifact-index-contract.md +++ b/docs/plans/2026-10-08-artifact-index-contract.md @@ -45,3 +45,46 @@ Every row exactly `{artifact_id,source_row,fields}`: source_row is original1-bas Tests launch the CLI as a subprocess with -B -S and propagate the active optimized mode. Before implementation, actual hosted RED must identify the missing CLI, not merely fail discovery/import/setup. Cover valid deterministic preservation and typing; multiple native ranges/default offsets/blank cells; every independently pinned identity; each required/duplicate/invalid flag; duplicate/nonfinite/deep/oversized JSON and canonical base64; native source/header/range/row/grid/type contradictions; unknown/duplicate artifact IDs and bindings; six explicit roles; unknown graph IDs; missing mappings; forged columns; private Source/Notes and unselected-row canaries absent from public stdout and refusal stderr; inert code/URL strings never fetched or executed. Positive selected public strings may themselves contain URLs/code as inert escaped data; omission is determined by explicit field/row policy. Keep fixtures synthetic and compact. Do not copy any real private capture into tests or the public repository. Complete this unit only after exact candidate hosted normal/optimized controls pass with full discovery, original failure/success archives and nonauthor source/privacy review. Real selected source projection/readback follows that tested parser; the capture SHA alone does not authenticate a Sheet revision. Native graph archive readback, evidence-public projection, Astro/build/browser/deployment and all other architecture outcomes remain separate work. + +## Proposed v2 extension: required node_id <-> artifact_path+sha binding (GB-5, proposal only) + +Status: PROPOSAL under GRAPH-BIND-01 (main#475 directive 6363671135, slice GB-5). Doc-only. This section changes no code, workflow, CI, required check or setting. v1 behavior above stays in force until a separate tested implementation lands with nonauthor review. Wiring any check into CI needs Dylan's approval, routed through CoS. Scientific effect NONE. A binding records where an artifact lives at a pinned revision. It is never acceptance, review or discharge evidence, and math stays fail-closed. + +### Motivation + +v1 bindings join graph nodes to Artifact Index rows only by `artifact_id`. `architecture/public-artifact-index-bindings.json` is currently `[]`, and all graph IDs are unmapped. Nothing records which repository file at which exact bytes backs a node, so no checker can report unbound or stale items. + +### Binding record (schema_version 2) + +Each binding is exactly this object. Unknown, missing or duplicate keys refuse: + +- `node_id`: graph node ID, using the same ASCII pattern and 192-character bound as v1 IDs. +- `artifact_id`: optional Artifact Index ID (v1 semantics). If present, it must be selected by policy. +- `repository`: `owner/name`, using the `[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+` pattern. +- `artifact_path`: a repo-relative POSIX path. It must be non-empty, contain no leading `/`, have no `.` or `..` segments, use no backslashes or control characters, and be at most 1024 UTF-8 bytes. +- `commit`: a 40-hex lowercase commit at which the path was observed. +- `blob_sha`: the 40-hex lowercase git blob SHA of `artifact_path` at `commit`. +- `sha256`: the 64-hex lowercase SHA-256 of the exact file bytes at that blob. +- `roles`: a non-empty, unique, lexically sorted list drawn from the v1 role set. + +A binding is unique per (`node_id`, `repository`, `artifact_path`). One node may bind several artifacts, and one artifact may back several nodes. Records sort by `node_id`, then `repository`, then `artifact_path`. + +### Required states (what a GB-6-style check reports) + +- **bound**: `artifact_path` exists at `commit`, and its blob and SHA-256 equal the pins. +- **stale**: the path exists at the checked ref, but its current blob differs from `blob_sha`. This is reported, not silently repinned. +- **missing**: the path does not exist at the checked ref. +- **unbound node**: a graph node with no binding record. +- **unbound artifact**: an in-scope file that no binding names. Scope is declared by an explicit, reviewed include-glob list in the bindings document, never inferred. + +In report mode the check lists all five states and exits 0. In enforce mode it exits nonzero on stale, missing or unbound items. Enforce mode is only used once Dylan approves CI wiring. Output is deterministic sorted ASCII JSON, matching v1 output rules. + +### Migration + +1. v1 `{node_id, artifact_id, roles}` records remain valid as v1. A v2 document carries `schema_version: 2` at the root and rejects v1-shaped records. +2. Pins come from a reviewed source commit, never from the working tree of an unreviewed head. +3. Per-lane binding PRs (GB-7+) populate records only after GB-1..GB-4 inventories report, one PR per area. + +### Non-goals + +No inference of bindings from titles or prose, no network fetch, no Sheet writes, and no change to required checks. Binding status does not change scientific status. From 86efd0dc2c2ccdbcabd9e16c7bd5c80d8cda7523 Mon Sep 17 00:00:00 2001 From: Dylan Roy <249851642+d6g8k5htny-coder@users.noreply.github.com> Date: Fri, 23 Oct 2026 06:27:08 -0500 Subject: [PATCH 2/2] docs: GB-5 amendment per review 5627565070 and agent 1/7 questions (doc only) --- .../2026-10-08-artifact-index-contract.md | 62 +++++++++++++------ 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/docs/plans/2026-10-08-artifact-index-contract.md b/docs/plans/2026-10-08-artifact-index-contract.md index ffd1b1de3..915b26219 100644 --- a/docs/plans/2026-10-08-artifact-index-contract.md +++ b/docs/plans/2026-10-08-artifact-index-contract.md @@ -48,43 +48,69 @@ Keep fixtures synthetic and compact. Do not copy any real private capture into t ## Proposed v2 extension: required node_id <-> artifact_path+sha binding (GB-5, proposal only) -Status: PROPOSAL under GRAPH-BIND-01 (main#475 directive 6363671135, slice GB-5). Doc-only. This section changes no code, workflow, CI, required check or setting. v1 behavior above stays in force until a separate tested implementation lands with nonauthor review. Wiring any check into CI needs Dylan's approval, routed through CoS. Scientific effect NONE. A binding records where an artifact lives at a pinned revision. It is never acceptance, review or discharge evidence, and math stays fail-closed. +Status: PROPOSAL under GRAPH-BIND-01 (main#475 directive 6363671135, slice GB-5), amended per review 522/5627565070 (agent 14) and questions from agent 7 (522/6363777423) and agent 1. Doc-only. It changes no code, workflow, CI, required check or setting. v1 behavior above stays in force until a separate tested implementation lands with nonauthor review. Wiring any check into CI needs Dylan's approval, routed through CoS. Scientific effect NONE. A binding records where an artifact lives at a pinned revision. It is never acceptance, review or discharge evidence, and math stays fail-closed. Every default below is fail-closed: when something is unclear, report it as not bound. ### Motivation v1 bindings join graph nodes to Artifact Index rows only by `artifact_id`. `architecture/public-artifact-index-bindings.json` is currently `[]`, and all graph IDs are unmapped. Nothing records which repository file at which exact bytes backs a node, so no checker can report unbound or stale items. -### Binding record (schema_version 2) +### Location and root shape -Each binding is exactly this object. Unknown, missing or duplicate keys refuse: +- v2 lives in a **new file**, `architecture/graph-artifact-bindings.v2.json`. The v1 file `architecture/public-artifact-index-bindings.json` stays untouched, so v1 readers (`architecture/artifact_index.py`, `tools/evidence_path.py`) keep working. +- The root is exactly `{"schema_version": 2, "node_source": {...}, "scope": [...], "bindings": [...]}`. Unknown, missing or duplicate keys refuse. + - `scope` is a sorted, unique list of reviewed repo-relative include globs. It defines the universe of in-scope artifacts. It is never inferred. Changing it is a reviewed doc/data change. + - `node_source` names the node universe: `{"kind": "graph-readback" | "site-projection", "repository", "path", "commit"}`, pinned to a 40-hex commit. `node_id` values and the "unbound node" set come only from this one declared export at that pin. GB-6 and GB-7 must not choose their own sources. -- `node_id`: graph node ID, using the same ASCII pattern and 192-character bound as v1 IDs. -- `artifact_id`: optional Artifact Index ID (v1 semantics). If present, it must be selected by policy. -- `repository`: `owner/name`, using the `[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+` pattern. +### Binding record + +Each entry in `bindings` is exactly this object: + +- `node_id` (**required**): an ID present in `node_source`. Same ASCII pattern and 192-character bound as v1 IDs. There is no non-node subject. +- `kind` (**required**): one of `file`, `tree`, `historical`, `absent`, `external_unverified` (see below). +- `repository`: `owner/name`. - `artifact_path`: a repo-relative POSIX path. It must be non-empty, contain no leading `/`, have no `.` or `..` segments, use no backslashes or control characters, and be at most 1024 UTF-8 bytes. -- `commit`: a 40-hex lowercase commit at which the path was observed. -- `blob_sha`: the 40-hex lowercase git blob SHA of `artifact_path` at `commit`. -- `sha256`: the 64-hex lowercase SHA-256 of the exact file bytes at that blob. +- `commit`: 40-hex lowercase. **Provenance only:** the commit where the pin was taken. +- `blob_sha`: 40-hex lowercase git object SHA. For `file`/`historical` it is the blob; for `tree` it is the tree object. +- `sha256`: 64-hex lowercase SHA-256 of the exact file bytes. Required for `file` and `historical`, and omitted for `tree`. +- `artifact_id` (**optional**): omitted unless the ID is already selected by `public-artifact-index-policy.json` (currently C151, C152, C215 only). `artifact_index.py` refuses anything else, so binding a file never requires a policy change. - `roles`: a non-empty, unique, lexically sorted list drawn from the v1 role set. +- `reason`, `last_seen_commit`, `url`: only for the kinds that require them (below). + +**Compact reference form** (for prose, logs and check output; the JSON record is authoritative): `owner/repo:path@commit#blob`, e.g. `d6g8k5htny-coder/main:architecture/artifact_index.py@7e9a532c13e3214bcb977a47372ad75c2c1b7b75#<40-hex blob>`. Use full 40-hex values in records, never abbreviations. A binding is unique per (`node_id`, `repository`, `artifact_path`). One node may bind several artifacts, and one artifact may back several nodes. Records sort by `node_id`, then `repository`, then `artifact_path`. -### Required states (what a GB-6-style check reports) +### Evaluation (all states at the checked ref) -- **bound**: `artifact_path` exists at `commit`, and its blob and SHA-256 equal the pins. -- **stale**: the path exists at the checked ref, but its current blob differs from `blob_sha`. This is reported, not silently repinned. +The checker evaluates every record at one **checked ref** (for example the current main commit), never at the record's own `commit`: + +- **bound**: `kind: file`, the path exists at the checked ref, its blob equals `blob_sha` and its bytes hash to `sha256`. (`kind: tree`: the tree object at the path equals `blob_sha`.) +- **stale**: the path exists at the checked ref but its blob or tree differs. Reported, never silently repinned. - **missing**: the path does not exist at the checked ref. -- **unbound node**: a graph node with no binding record. -- **unbound artifact**: an in-scope file that no binding names. Scope is declared by an explicit, reviewed include-glob list in the bindings document, never inferred. +- **historical**: a `kind: historical` record (see Q1). Reported separately, never counted as bound. +- **absent**: a `kind: absent` record. Counted with missing, never bound. +- **external_unverified**: a `kind: external_unverified` record. Never bound. +- **unbound node**: a node in `node_source` that has no record of its own. +- **unbound artifact**: a file matched by `scope` that no `file` record names. + +In report mode the check lists all states and exits 0. In enforce mode it exits nonzero on anything other than bound. Enforce mode is only used once Dylan approves CI wiring. Output is deterministic sorted ASCII JSON, matching v1 output rules. + +### Fail-closed answers to open questions -In report mode the check lists all five states and exits 0. In enforce mode it exits nonzero on stale, missing or unbound items. Enforce mode is only used once Dylan approves CI wiring. Output is deterministic sorted ASCII JSON, matching v1 output rules. +1. **Deleted file at an old commit** (e.g. `STATUS_RN_UNIF.md@a3e42254`): allowed only as `kind: historical`, pinned by `commit`, `blob_sha` and `sha256`. It's reported as historical and never as current-bound. *Why:* the bytes are still verifiable from git history, but a node that only resolves to deleted content isn't backed by the current project. +2. **Directory as a source**: not as a loose path. Bind each file, or use `kind: tree` with an explicit tree `blob_sha`. *Why:* a path with no hash can change silently, and a tree SHA pins every byte below it. +3. **URL or `external:` sources**: never bound. Use `kind: external_unverified` with `url`, until a pinned hash or an archived copy exists in a repo, which can then be bound as `file`. *Why:* the checker does no network fetch and can't verify remote bytes. +4. **Inherited bindings from linked nodes**: not allowed. Every node needs its own record, and a node without one is unbound. *Why:* inheritance would hide gaps and let one binding stand in for many unverified claims. +5. **Absent files**: yes, explicit `kind: absent` with a required `reason` and `last_seen_commit`. It counts as missing, never bound. *Why:* it records known gaps on purpose without faking a pin. +6. **Files with no graph node** (agent 7 Q1): keep `node_id` required. No non-node subjects and no new Artifact Index rows. Such files stay reported as **unbound artifact**. A GB-7 lane binds a file only once a real node exists for it. Creating nodes is a separate, reviewed graph change, not part of a binding PR. +7. **Do `tools/` files need nodes?** (agent 7 Q2): no. `tools/` is excluded from the default `scope`, while `architecture/` stays in scope. Tool outputs, or the nodes they serve, are bound where those exist. A specific tool joins `scope` only through a reviewed scope change, when it is itself a public artifact (for example an export CLI cited from a node page). *Why:* this keeps unbound counts meaningful and avoids inventing nodes. ### Migration -1. v1 `{node_id, artifact_id, roles}` records remain valid as v1. A v2 document carries `schema_version: 2` at the root and rejects v1-shaped records. +1. v1 `{node_id, artifact_id, roles}` records remain valid in the v1 file. The v2 file rejects v1-shaped records. 2. Pins come from a reviewed source commit, never from the working tree of an unreviewed head. -3. Per-lane binding PRs (GB-7+) populate records only after GB-1..GB-4 inventories report, one PR per area. +3. Per-lane binding PRs (GB-7+) populate the v2 file only after GB-1..GB-4 inventories report, one PR per area. ### Non-goals -No inference of bindings from titles or prose, no network fetch, no Sheet writes, and no change to required checks. Binding status does not change scientific status. +No inference of bindings from titles or prose, no inheritance, no network fetch, no Sheet writes, no node creation and no change to required checks. Binding status does not change scientific status.