diff --git a/.agents/knowledge/README.md b/.agents/knowledge/README.md index 2db0a6c4..2d7b8882 100644 --- a/.agents/knowledge/README.md +++ b/.agents/knowledge/README.md @@ -6,7 +6,7 @@ Durable protocol and tooling facts. Normative specs live in [`specs/`](../specs/ | Doc | Category | Source | Summary | |-----|----------|--------|---------| -| [`architecture-patterns/spoke-codegen-pipeline.md`](architecture-patterns/spoke-codegen-pipeline.md) | architecture-patterns | current `schemas/**/*.schema.json`, `tooling/codegen` and generated trees | jstt+typify orchestrator over **114** hand-authored schemas; each generated tree is **114 modules + 5 barrels = 119 files**; `verify-codegen` regenerates both trees, asserts the schema count and opaque-JSON types, then runs `cargo check --workspace`; rust-gen fail-fast; **presence-sensitive arrays** — six byte-bound modules module-wide, plus `Content.cognition` in all 15 carrier modules / 17 clone types (unrelated arrays keep `Vec` + `is_empty`); typify nominal-clone canonical-import guide and Builder construction; **regeneration ripple** — compiling generated bytes does not cover downstream handlers (land ABI + consumer updates together) | +| [`architecture-patterns/spoke-codegen-pipeline.md`](architecture-patterns/spoke-codegen-pipeline.md) | architecture-patterns | current `schemas/**/*.schema.json`, `tooling/codegen` and generated trees | jstt+typify orchestrator over **114** hand-authored schemas; each generated tree is **114 modules + 5 barrels = 119 files**; `verify-codegen` checks the committed trees — schema count, opaque-JSON types, TypeScript typecheck and `cargo check --workspace`; rust-gen fail-fast; **presence-sensitive arrays** — six byte-bound modules module-wide, plus `Content.cognition` in all 15 carrier modules / 17 clone types (unrelated arrays keep `Vec` + `is_empty`); typify nominal-clone canonical-import guide and Builder construction; **regeneration ripple** — compiling generated bytes does not cover downstream handlers (land ABI + consumer updates together) | | [`architecture-patterns/mind-axis-ownership-boundary.md`](architecture-patterns/mind-axis-ownership-boundary.md) | architecture-patterns | current cognition schema, data contract and Memory contract | One current authority per holder: `KnowledgeEntry.modules.cognition`; open `modules.mental` keeps nine fields with `beliefs` as derivative summary; `WorldFactRecord` stays world-side; `MindState`/`MindDelta` are derivative L5 presentation with RFC 6901 pointers; Memory `Content.cognition` is recorded-at-time and never mutates current authority; complete `(kind, namespace, id)` reference identity; `assessed` vs `no_record` projection; dual-SSOT prevention and rejection table | | [`architecture-patterns/mind-axis-ops-extraction-gate.md`](architecture-patterns/mind-axis-ops-extraction-gate.md) | architecture-patterns | current `spoke-operations` cognition exports and shipped consumers | `spoke-operations` ships only pure validators (cognition record/content/module/observation/filter/selection/projection, MindState RFC 6901 pointer gate) plus deterministic match/select/project serving KE `Scope`/assemble and Memory `cognition_filter`; checker Finding patterns, belief revision, delta apply/replay, ordering, scoring and ranking stay out; further helper families gated on two consumers with dual-language parity and shared vectors | | [`architecture-patterns/connect-error-taxonomy-layering.md`](architecture-patterns/connect-error-taxonomy-layering.md) | architecture-patterns | compound 2026-08-13 (protocol_version_mismatch) | Four-layer error chain (CoreError→ConnectError→RemoteAdapterError→FfiError); dual FFI surface; ordinal stability; frozen contract rule | diff --git a/.agents/knowledge/architecture-patterns/spoke-codegen-pipeline.md b/.agents/knowledge/architecture-patterns/spoke-codegen-pipeline.md index c894e9a9..59a3c419 100644 --- a/.agents/knowledge/architecture-patterns/spoke-codegen-pipeline.md +++ b/.agents/knowledge/architecture-patterns/spoke-codegen-pipeline.md @@ -28,7 +28,7 @@ Hand-authored JSON Schema must produce both TypeScript (`@42ch/spoke-schemas`) a 1. **SSOT** — only `schemas/**/*.schema.json` are hand-authored; generated trees are committed. 2. **Orchestrator** — `tooling/codegen` (`pnpm -F @42ch/spoke-codegen codegen` → `node tooling/codegen/src/run.mjs`) walks schemas, localizes `$ref`s for typify, and emits mirrored `generated/{common,connect,data,ops}/` trees in both packages. -3. **Verify** — `pnpm run verify-codegen` runs `codegen` → `tooling/codegen/assert-schema-count.mjs` → `tooling/codegen/assert-opaque-json-types.mjs` → `node --test tooling/codegen/test/deep-ref-hoist.test.mjs` → `cargo check --workspace`. +3. **Verify** — `pnpm run verify-codegen` checks the committed trees: `tooling/codegen/assert-schema-count.mjs` → `tooling/codegen/assert-opaque-json-types.mjs` → `node --test tooling/codegen/test/deep-ref-hoist.test.mjs` → `@42ch/spoke-schemas` typecheck → `cargo check --workspace`. Regeneration is the author step (`pnpm run codegen`); CI verifies the committed output that ships, never a regenerated worktree. 4. **Fail-fast counts** — `assert-schema-count.mjs` holds `EXPECTED_SCHEMA_COUNT = 114`; `tooling/codegen/rust-gen/src/main.rs` holds the same constant and returns non-zero unless exactly 114 Rust schema modules are written. Bump both constants in the same commit as the schema change and the regenerated output. 5. **Closed ops responses** — mutually exclusive success/error shapes use draft-07 `oneOf` (see `assemble-response.schema.json`). 6. **Opaque JSON** — `#/definitions/OpaqueJson` must be an **empty schema object `{}`**. Consuming properties `$ref` that definition (e.g. `ComputableLogChange.previous` / `.next`, `ExtractionRunMetadata.coverage_hint`). Generators emit any-JSON types (`unknown` / `OpaqueJson` in TS; `serde_json::Value` in Rust). diff --git a/.agents/knowledge/tooling-decisions/ci-assembled-committed-native-artifacts.md b/.agents/knowledge/tooling-decisions/ci-assembled-committed-native-artifacts.md index 558f04d7..f977f7d7 100644 --- a/.agents/knowledge/tooling-decisions/ci-assembled-committed-native-artifacts.md +++ b/.agents/knowledge/tooling-decisions/ci-assembled-committed-native-artifacts.md @@ -37,13 +37,13 @@ A simulated compiler can exercise source-identity decisions in an isolated Git r | Swift | `xcframework.yml` uses the pinned, locked staged build for the three-slice bundle. The uploaded manifest and producer record bind transferred files to the run's source and observed compiler. A committed consumer smoke exercises the committed macOS slice. | | Go Darwin | The existing maintainer recipe builds both committed Darwin targets, copies their dylibs and assigns `@rpath/libspoke_connect.dylib`. Retain the local source, toolchain, SDK, flags, full-byte comparisons and applied hashes. | -Both C header hashes are recorded per RID; header byte representation follows the checkout's LF attributes. Native binaries and each RID's metadata remain one source-bound pair; a bundled sibling entry is not evidence for a different RID's build. +Recorded hashes describe the bytes a build produced; they are audit data, not a CI gate. The committed carriers are covered by the C ABI symbol check and the C++ smoke, which exercise behavior. Both C header hashes are recorded per RID; header byte representation follows the checkout's LF attributes. Native binaries and each RID's metadata remain one source-bound pair; a bundled sibling entry is not evidence for a different RID's build. Swift static archives and C dynamic carriers use git-lfs. Applied LFS pointer OIDs must agree with the recorded artifact hashes. Go dylibs remain ordinary Git objects for module-proxy consumption. The C import library and provenance are ordinary Git objects. ### Keep the Swift refresh path usable and fail-closed -The committed Swift consumer smoke exercises the committed macOS slice. The staged producer builds and uploads the refresh bundle; the manifest and producer record travel with the artifact, so a maintainer can apply a validated refresh without comparing two build trees. +The committed Swift consumer smoke exercises the committed macOS slice; no regeneration byte diff runs in CI. The staged producer builds and uploads the refresh bundle; the manifest and producer record travel with the artifact, so a maintainer can apply a validated refresh without comparing two build trees. `apply-xcframework-artifact.sh ` requires the expected completed workflow/job and successful build, manifest, provenance and upload steps. A failed run is usable only when its failed checks are confined to the explicitly named consumer-smoke check. Other failures, incomplete/cancelled runs or inconsistent outcomes are rejected. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70618e7e..1fc83622 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ Useful scripts (repo root): | Script | Purpose | |--------|---------| | `pnpm run codegen` | Regenerate TypeScript and Rust types from `schemas/` | -| `pnpm run verify-codegen` | Codegen + schema-count assert + opaque-JSON type contract + `cargo check --workspace` | +| `pnpm run verify-codegen` | Schema-count assert + opaque-JSON type contract + typecheck and compile of the committed generated trees | | `pnpm run typecheck` | Typecheck all workspace TS packages (`@42ch/spoke-schemas`, `@42ch/spoke-operations`, `@42ch/spoke-connect`, `@42ch/spoke-demo-server`, `@42ch/spoke-demo-client`) — warm-tree helper; the cold-clone gate is `ci:typescript` | | `pnpm run ci:typescript` | Cold-clone gate mirroring the ci.yml `typescript` job stage chain in dependency order, then the demo typechecks + `test:demo` | | `pnpm run build:schema` / `build:operations` | Build published npm packages | @@ -121,7 +121,7 @@ Refresh the committed artifact from a run in one command (requires the `gh` CLI, ./tooling/connect/apply-xcframework-artifact.sh ``` -The script verifies the run's provenance — the `Xcframework` workflow, completed producer steps for the build, manifest, provenance, and upload, and either success or failures limited to the consumer-smoke check. The producer record must name the run head as both its declared `sourceHead` and its actual `checkoutRevision`, so a run built from a different checkout — a pull-request virtual merge records the merge commit, not the PR head — can never be applied as a head build. The run `headSha` must match the current checkout (override with `--allow-sha ` only to deliberately pin an older build; the override never relaxes the producer-record checks). It verifies the artifact's hash manifest and producer record before applying the built tree and staging the LFS pointers. The copy itself is content-aware — `rsync -c` compares checksums rather than size and mtime, because same-size files sharing a coarse mtime would otherwise be skipped, reporting success while leaving the old bytes — and after the copy the script re-verifies the delivered tree against the artifact's hash manifest before any staging or sidecar write, so a transfer that reports success without delivering the authenticated bytes refuses with no staged changes and no provenance sidecar. Commit with the suggested line — `build(connect): refresh xcframework from CI artifact ` — using normal maintainer credentials. Builds are not bit-reproducible across runs; the transfer manifest and producer record identify the applied bytes. +The script verifies the run's provenance — the `Xcframework` workflow, completed producer steps for the build, manifest, provenance, and upload, and either success or failures limited to the consumer-smoke check. The producer record must name the run head as both its declared `sourceHead` and its actual `checkoutRevision`, so a run built from a different checkout — a pull-request virtual merge records the merge commit, not the PR head — can never be applied as a head build. The run `headSha` must match the current checkout (override with `--allow-sha ` only to deliberately pin an older build; the override never relaxes the producer-record checks). It verifies the artifact's hash manifest and producer record before applying the built tree and staging the LFS pointers. The copy itself is content-aware — `rsync -c` compares checksums rather than size and mtime, because same-size files sharing a coarse mtime would otherwise be skipped, reporting success while leaving the old bytes — and after the copy the script re-verifies the delivered tree against the artifact's hash manifest before any staging or sidecar write, so a transfer that reports success without delivering the authenticated bytes refuses with no staged changes and no provenance sidecar. Commit with the suggested line — `build(connect): refresh xcframework from CI artifact ` — using normal maintainer credentials. Bit-identical output requires identical inputs (source, lockfile, toolchain, target and output path); a rebuild on a different dependency or toolchain basis need not match. The transfer manifest and producer record identify the applied bytes. ## Refreshing the C carrier natives diff --git a/docs/reference/protocol.md b/docs/reference/protocol.md index 7ab229bb..f6337386 100644 --- a/docs/reference/protocol.md +++ b/docs/reference/protocol.md @@ -20,7 +20,7 @@ Six interaction envelopes ([`schemas/connect/`](https://github.com/42ch-dev/spok ## Schema inventory and codegen posture -The wire inventory is **114 committed `*.schema.json` files**: 2 common + 24 data + 82 ops + 6 connect envelopes. The optional `spoke-memory` family contributes 79 of them (13 data models + 33 request/response pairs). Baseline integrators use **21** of those files (2 common + 9 data + 10 baseline ops): the nine baseline data schemas include `ToolDescriptor`, while `CognitionRecord` and `MindState` are the two optional non-memory data files. `schemas/` is the only hand-authored wire truth; generated TypeScript (`@42ch/spoke-schemas`) and Rust (`spoke-schemas`) output is committed and mirrors the schema tree. `pnpm run verify-codegen` regenerates both trees, checks the opaque-JSON type contract and compiles the workspace; schema changes and regenerated output land in the same commit. +The wire inventory is **114 committed `*.schema.json` files**: 2 common + 24 data + 82 ops + 6 connect envelopes. The optional `spoke-memory` family contributes 79 of them (13 data models + 33 request/response pairs). Baseline integrators use **21** of those files (2 common + 9 data + 10 baseline ops): the nine baseline data schemas include `ToolDescriptor`, while `CognitionRecord` and `MindState` are the two optional non-memory data files. `schemas/` is the only hand-authored wire truth; generated TypeScript (`@42ch/spoke-schemas`) and Rust (`spoke-schemas`) output is committed and mirrors the schema tree. `pnpm run verify-codegen` checks the committed trees: schema count, the opaque-JSON type contract, TypeScript typecheck and `cargo check --workspace`; schema changes and regenerated output land in the same commit. ## Extensions contract diff --git a/docs/zh/reference/protocol.md b/docs/zh/reference/protocol.md index 6653bbc9..0af9f2f6 100644 --- a/docs/zh/reference/protocol.md +++ b/docs/zh/reference/protocol.md @@ -20,7 +20,7 @@ SPOKE 是面向叙事产品的共享**线上方言(wire dialect)**:一套 ## Schema 清单与代码生成姿态 -线上清单为 **114 个已提交的 `*.schema.json`**:2 common + 24 data + 82 ops + 6 connect 信封。可选 `spoke-memory` 族贡献其中 79 个(13 个数据模型 + 33 组请求/响应配对)。基线集成方使用其中的 **21** 个 schema 文件(2 common + 9 data + 10 基线 ops):九个基线数据 schema 包含 `ToolDescriptor`,而 `CognitionRecord` 与 `MindState` 是两个可选的非记忆数据文件。`schemas/` 是唯一手写线上真源;生成的 TypeScript(`@42ch/spoke-schemas`)与 Rust(`spoke-schemas`)输出提交入库并镜像 schema 树。`pnpm run verify-codegen` 重新生成两棵生成树,检查 opaque JSON 类型契约并编译工作区;schema 变更与重新生成输出落在同一提交。 +线上清单为 **114 个已提交的 `*.schema.json`**:2 common + 24 data + 82 ops + 6 connect 信封。可选 `spoke-memory` 族贡献其中 79 个(13 个数据模型 + 33 组请求/响应配对)。基线集成方使用其中的 **21** 个 schema 文件(2 common + 9 data + 10 基线 ops):九个基线数据 schema 包含 `ToolDescriptor`,而 `CognitionRecord` 与 `MindState` 是两个可选的非记忆数据文件。`schemas/` 是唯一手写线上真源;生成的 TypeScript(`@42ch/spoke-schemas`)与 Rust(`spoke-schemas`)输出提交入库并镜像 schema 树。`pnpm run verify-codegen` 校验已提交的生成树:schema 数量、opaque JSON 类型契约、TypeScript typecheck 与 `cargo check --workspace`;schema 变更与重新生成输出落在同一提交。 ## 扩展契约 diff --git a/package.json b/package.json index f2fbec02..b61813dc 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "//": "Cold-clone gate is `ci:typescript` (inlined superset of the ci.yml `typescript` job: `build:operations` precedes every typecheck that resolves @42ch/spoke-operations from dist/, then the demo typechecks + `test:demo`). The composite `typecheck` script is a warm-tree helper only.", "scripts": { "codegen": "pnpm -F @42ch/spoke-codegen codegen", - "verify-codegen": "pnpm run codegen && node tooling/codegen/assert-schema-count.mjs && node tooling/codegen/assert-opaque-json-types.mjs && node --test tooling/codegen/test/deep-ref-hoist.test.mjs && cargo check --workspace", + "verify-codegen": "node tooling/codegen/assert-schema-count.mjs && node tooling/codegen/assert-opaque-json-types.mjs && node --test tooling/codegen/test/deep-ref-hoist.test.mjs && pnpm -F @42ch/spoke-schemas typecheck && cargo check --workspace", "typecheck": "pnpm -F @42ch/spoke-schemas typecheck && pnpm -F @42ch/spoke-operations typecheck && pnpm -F @42ch/spoke-connect typecheck && pnpm -F @42ch/spoke-demo-server typecheck && pnpm -F @42ch/spoke-demo-client typecheck", "build:schema": "pnpm -F @42ch/spoke-schemas build", "build:operations": "pnpm -F @42ch/spoke-operations build",