Skip to content
Merged
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
2 changes: 1 addition & 1 deletion .agents/knowledge/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

README index summary drops the generated-tree freshness dimension the row previously carried · 🔵 nit

[DOCS-02] README index summary drops the generated-tree freshness dimension the row previously carried

  • Evidence: .agents/knowledge/README.md:9 — the codegen row summary changed from "verify-codegen regenerates both trees, asserts the schema count and opaque-JSON types, then runs cargo check --workspace" to "verify-codegen checks the committed trees — schema count, opaque-JSON types, TypeScript typecheck and cargo check --workspace".
  • Impact: Both halves of the new wording are factually correct against the current script (package.json:15: assert-schema-count → assert-opaque-json-types → deep-ref-hoist test → pnpm -F @42ch/spoke-schemas typecheck → cargo check --workspace) and against packages/spoke-schemas/package.json:37 (typecheck: tsc --noEmit exists). The residual reader cost is only that the index row now reads as a complete verification list while the freshness question (see DOCS-01) is the same one; this is a wording consequence of the same change, not an independent wrong outcome.
  • Effort: XS
  • Risk: LOW — summary text only.
  • Confidence: HIGH (opened the row and both scripts).
  • Merge class: nit
  • Fix sketch: Align the summary row's wording with the corrected posture once DOCS-01 is settled; no behavior change.

| [`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 |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Knowledge doc presents CI as verifying committed generated trees, but no chain step compares them to schemas/ · 🟡 may-fix

[DOCS-01] Knowledge doc presents CI as verifying committed generated trees, but no chain step compares them to schemas/

  • Evidence: .agents/knowledge/architecture-patterns/spoke-codegen-pipeline.md:31 — Decision step 3 now reads: "pnpm run verify-codegen checks the committed trees: tooling/codegen/assert-schema-count.mjs → tooling/codegen/assert-opaque-json-types.mjs → node --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."
  • Evidence: tooling/codegen/assert-schema-count.mjs:29-31 — EXPECTED_SCHEMA_COUNT = 114; the script only counts schemas/**/*.schema.json files and never enumerates packages/spoke-schemas/src/generated or the Rust generated tree, so a schema body edit that skips regeneration leaves the count at 114 and passes.
  • Evidence: tooling/codegen/assert-opaque-json-types.mjs:1-20 — the checker reads committed generated TS (packages/spoke-schemas/src/generated) and asserts the opaque-JSON shape; it is self-consistent against stale output, not proof of freshness.
  • Evidence: .github/workflows/ci.yml:87-89 — the verify-codegen job runs only pnpm run verify-codegen; .github/workflows/release.yml:163-164 does the same before publish. Neither adds a post-step git diff --exit-code, and grep across .github/workflows/ finds no other codegen invocation.
  • Impact: The doc is the durable tooling fact surface loaded before touching schemas/. Its "CI verifies the committed output that ships" wording, placed immediately after removal of the regeneration step, tells a reader that a green verify-codegen certifies the committed trees are current with the hand-authored SSOT declared in the same doc's Problem s…

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).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <run-id>` 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.

Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -121,7 +121,7 @@ Refresh the committed artifact from a run in one command (requires the `gh` CLI,
./tooling/connect/apply-xcframework-artifact.sh <run-id>
```

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 <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 <run-id>` — 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 <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 <run-id>` — 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

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/zh/reference/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 变更与重新生成输出落在同一提交。

## 扩展契约

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

verify-codegen no longer executes the generator, so CI never proves the schema set is still generatable · 🟡 may-fix

  • Evidence: package.json:15 — the changed verify-codegen chain is now assert-schema-count.mjs → assert-opaque-json-types.mjs → node --test deep-ref-hoist.test.mjs → pnpm -F @42ch/spoke-schemas typecheck → cargo check --workspace; the leading pnpm run codegen was deleted. tooling/codegen/assert-schema-count.mjs:6-9 still describes the author procedure as "Run pnpm run codegen; commit schema + generated output + this constant in one commit. pnpm run verify-codegen must PASS", so step 4 no longer executes step 3. The two CI consumers run this exact chain: .github/workflows/ci.yml:87-89 ("Verify codegen output": pnpm run verify-codegen) and .github/workflows/release.yml:163-164. tooling/codegen/assert-opaque-json-types.mjs:14 ("Wire it from pnpm run verify-codegen") is unaffected because that script reads schemas/, not generated output.
  • Impact: Before this change the CI job proved two things — the committed trees compile and schemas/ still generates. After it, the generator (tooling/codegen/src/run.mjs → jstt + typify, plus rust-gen's exact-114 fail-fast) is exercised by no CI job at all. Concretely: a PR that edits schemas/**/*.schema.json, fails to regenerate (the case the new docs warn about), and commits stale-but-compiling generated output now passes verify-codegen green, whereas the previous chain failed at codegen/rust-gen for any schema the generators reject. The committed generated trees that ship (and that docs/reference/protocol.md:23 / docs/zh/reference/protocol.md:23 now describe as "checked") can therefore disagree with the hand-authored SSOT with no red check. Note the pre-existing part: drift itself was never asserted (no git diff --exit-code after regeneration), so this finding is limited to the newly removed generatability guard, not to a new drift detector that never exis…

"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",
Expand Down
Loading