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` asserts the schema count, opaque-JSON types, the generated-Rust size bound and zero drift, 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** — zero-drift proof covers generated bytes, not downstream compilability (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` 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/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 @@ -64,7 +64,7 @@ When consolidating fragmented conceptual content (e.g., merging the old 7-page `

1. **Binding package coordinates** — inline on the native-bindings how-to (NuGet `42ch.Spoke.Connect`, Maven `dev.42ch:spoke-connect`, SPM `SpokeConnect`, Go module path, PyPI `spoke-connect`). Do not leave coordinates behind a spec link.
2. **Domain Profile open-string vocabulary tables** — per-profile vocabulary (beat types, activation fields, pack dialect keys, placement hints) on the consolidated `explanation/domain-profiles.md`. Full mapping matrices remain agent SSOT in specs.
3. **Schema inventory count + codegen verify posture** — explicit subsection on `reference/protocol.md` (114 committed `*.schema.json` files, mirrored by `tooling/codegen/assert-schema-count.mjs`; `verify-codegen` drift gate).
3. **Schema inventory count + codegen verify posture** — explicit subsection on `reference/protocol.md` (114 committed `*.schema.json` files, mirrored by `tooling/codegen/assert-schema-count.mjs`; `verify-codegen` regeneration posture).
4. **Discovery / peering boundary** (explicit peering as the discovery path) — affirmative paragraph on `reference/connect.md`.
5. **Operations purity boundary** (no I/O, storage, LLM, HTTP, ranking, retrieval, silent auto-promote) — affirmative form on `reference/ops.md` and `how-to/orchestrate-ops.md`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,13 @@ 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` → `tooling/codegen/assert-generated-rust-size.mjs` → `git diff --exit-code` on both generated trees → `cargo check --workspace`.
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`.
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).
6b. **Annotated `$ref` normalization** — a bare `$ref` to the untyped `{}` target emits `unknown`, but a `$ref` carrying a sibling `description` makes jstt emit an object-index map (`{ [k: string]: unknown | undefined }`), silently narrowing any-JSON to object shape. The orchestrator normalizes annotation-bearing opaque refs to the `allOf` form before generation, and `assert-opaque-json-types.mjs` checks the generated types with a negative control that names the regressed field. Connect `payload` / `auth` / `proof` are the precedent; adapting such consumers is a type-level mechanical change (object-map → `unknown`), not a wire change.
7. **Duplicate generated types (strategy A)** — document typify nominal duplication as known generator behavior; integrators use canonical `common/` imports. No orchestrator dedupe.
8. **Generated Rust size bound** — `assert-generated-rust-size.mjs` caps the three rustfmt-formatted memory response files (`memory_exports_get_response.rs`, `memory_imports_stage_request.rs`, `memory_receipts_get_response.rs`) at 2 MiB to catch runaway shared-definition growth. Raise the bound only with the legitimate schema change and the regenerated file in the same commit.
9. **Release tooling tests** — `pnpm run test:release` runs pure unit tests for lockstep assert/bump scripts (temp fixtures; optional `SPOKE_REPO_ROOT` for harness isolation). Wired into the CI `typescript` job.
8. **Release tooling tests** — `pnpm run test:release` runs pure unit tests for lockstep assert/bump scripts (temp fixtures; optional `SPOKE_REPO_ROOT` for harness isolation). Wired into the CI `typescript` job.

## Schema inventory and generated layout

Expand Down Expand Up @@ -78,9 +77,9 @@ Raw struct literals (`Scope { scope_id: ..., ... }`) are **field-exhaustive by t

Regenerating binding trees changes the **interface downstream host code must implement**, not only the generated files. A new callback method on `PortsHandler` makes every existing implementation of that interface (per-language smoke files, host staging) uncompilable until it implements the method:

- The ripple lands **outside** the generated trees, so a zero-drift, committed regeneration can leave channels unbuildable when their handlers were not updated in the same change.
- The ripple lands **outside** the generated trees, so a committed regeneration can leave channels unbuildable when their handlers were not updated in the same change.
- Per-task diff review cannot see this class: each diff looks correct in isolation, and the breakage appears only when the generated tree and its consumers compile together.
- Handle it deliberately: land the generated ABI and the downstream handler updates as **one task**, or make the regenerating task's acceptance include "the consuming smoke/host sources still compile". Zero-drift proof covers generated bytes; it says nothing about downstream compilability.
- Handle it deliberately: land the generated ABI and the downstream handler updates as **one task**, or make the regenerating task's acceptance include "the consuming smoke/host sources still compile". Compiling the generated trees says nothing about downstream handler sources.

## What not to do

Expand Down
Original file line number Diff line number Diff line change
@@ -1,20 +1,18 @@
---
module: connect / native artifact provenance
date: 2026-08-18
last_updated: 2026-11-08
last_updated: 2026-11-16
problem_type: tooling_decision
category: tooling-decisions
severity: medium
tags:
- native-artifacts
- xcframework
- provenance
- source-freshness
- lfs
- reproducibility
applies_when:
- Refreshing committed native carriers
- Verifying source-to-artifact freshness
---

# Source-bound committed native artifacts
Expand All @@ -36,22 +34,22 @@ A simulated compiler can exercise source-identity decisions in an isolated Git r
| Carrier | Existing producer and retained evidence |
|---|---|
| C/C++ | `cpp-connect.yml` produces macOS and Windows artifacts. Each RID keeps its own source revision, target, observed Rust/compiler versions, flags, artifact hashes and both `headerSha256`/`hppSha256`. Apply each RID's files and entry from its own producer artifact. |
| 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. The committed-versus-built decision follows upload. |
| 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 required per RID; missing or mismatching values fail verification. 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.
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, then the two-tree verifier compares it with the committed tree. A stale committed carrier can therefore fail freshness while leaving a valid refresh artifact available.
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.

`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 committed freshness and consumer-smoke checks. Other failures, incomplete/cancelled runs or inconsistent outcomes are rejected.
`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.

Normal application matches the checkout HEAD to the run's source. Before replacing the bundle, the script validates every transferred manifest entry, binds producer `sourceHead` to the run head, checks the embedded manifest against the transferred manifest and requires an observed compiler value. The sidecar records the actual run conclusion, source and application head. An intentional explicit source override is recorded separately.

A second download of the same build can verify transfer and application identity. Independent reproducibility requires another real source build with equivalent inputs. The producer's failing old-tree comparison, the applied artifact's passing integrity check and later delivery CI retain their distinct results.
A second download of the same build can verify transfer and application identity. Independent reproducibility requires another real source build with equivalent inputs. The transfer manifest proves the shipped bytes; behavior comes from the committed carrier checks.

### Compare independent builds with identical complete inputs

Expand All @@ -65,16 +63,16 @@ Producer-level normalization of `Info.plist` `AvailableLibraries` ordering stabi

## Why This Matters

Source-bound producer records explain which implementation consumers receive. Required committed-carrier checks preserve drift detection, while upload-before-decision and the guarded application policy make a legitimate refresh possible. Independent cold builds and whole-file mismatch controls establish reproducibility within their declared input boundary.
Source-bound producer records explain which implementation consumers receive. Committed-carrier symbol and smoke checks cover behavior, while the transfer manifest and the guarded application policy make a legitimate refresh possible. Independent cold builds and whole-file mismatch controls establish reproducibility within their declared input boundary.

## When to Apply

- A compiled dependency or FFI implementation change affects committed carriers.
- A required freshness check reports drift and a genuine refresh artifact is available.
- A maintainer refreshes a committed carrier from a CI artifact.
- A native comparison needs to distinguish changed inputs from same-input nondeterminism.

## References

- [Native-binding channels](../../adr/implemented/architecture/2026-08-03-connect-binding-channels.md)
- [Maintainer carrier procedures](../../../CONTRIBUTING.md)
- Source: `.github/workflows/cpp-connect.yml`, `.github/workflows/xcframework.yml`, `tooling/connect/cpp-build.mjs`, `apply-xcframework-artifact.sh`, `verify-xcframework-drift.sh`.
- Source: `.github/workflows/cpp-connect.yml`, `.github/workflows/xcframework.yml`, `tooling/connect/cpp-build.mjs`, `apply-xcframework-artifact.sh`, `tooling/connect/xcframework-manifest.sh`.
2 changes: 1 addition & 1 deletion .agents/specs/connect/connect-cpp-binding.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ C++20 generator integration, vcpkg/Conan, public Release archives, additional pl
- `crates/spoke-connect/bindings/cpp/native/provenance.json` — per-RID source revision, toolchain and artifact hashes (`headerSha256`, `hppSha256`, artifact SHA-256).
- `crates/spoke-connect/bindings/cpp/Smoke/` (`main.cpp`, `convenience.cpp`, `support.hpp`) and `crates/spoke-connect/bindings/cpp/ue/` (`SpokeConnect.Build.cs`, `README.md`).
- `crates/spoke-connect-capi/` — the workspace-private carrier crate (`publish = false`).
- `tooling/connect/cpp-symbol-check.mjs`, `tooling/connect/cpp-smoke.mjs`, `tooling/connect/cpp-build.mjs` — drift gate, smoke runner and native producer/verifier.
- `tooling/connect/cpp-symbol-check.mjs`, `tooling/connect/cpp-smoke.mjs`, `tooling/connect/cpp-build.mjs` — drift gate, smoke runner and native producer.
- `.github/workflows/cpp-connect.yml` — per-PR carrier lanes; `.gitattributes` — git-lfs rules for the carrier libraries.
- `crates/spoke-connect/tests/fixtures/golden-hello.json` — the golden hello bytes the smokes assert.

Expand Down
6 changes: 0 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -248,12 +248,6 @@ jobs:
cargo build -p spoke-connect --features ffi,remote-adapter
cargo test -p spoke-connect --features ffi,remote-adapter

# First-party uniffi languages only (Swift, Python). C# and Go use vendored
# uniffi-bindgen forks under bindings/{csharp,go}/bindgen/ and are excluded.
- name: Verify binding regeneration (no drift)
if: needs.changes.outputs.code == 'true'
run: ./tooling/connect/verify-binding-regen.sh

csharp-connect:
needs: changes
name: csharp-connect
Expand Down
16 changes: 2 additions & 14 deletions .github/workflows/cpp-connect.yml
Original file line number Diff line number Diff line change
Expand Up @@ -121,12 +121,6 @@ jobs:
throw "cl.exe version probe failed with exit code $LASTEXITCODE"
}

- name: Verify committed Windows provenance
if: needs.changes.outputs.code == 'true'
id: committed_provenance
continue-on-error: true
run: node tooling/connect/cpp-build.mjs --verify --target x86_64-pc-windows-msvc

- name: Check committed C ABI symbols
if: needs.changes.outputs.code == 'true'
id: committed_symbols
Expand Down Expand Up @@ -176,7 +170,7 @@ jobs:
retention-days: 5

- name: Fail on committed carrier errors
Comment thread
auto-wood marked this conversation as resolved.
Resolved
if: always() && (steps.committed_provenance.outcome == 'failure' || steps.committed_symbols.outcome == 'failure' || steps.committed_smoke.outcome == 'failure')
if: always() && (steps.committed_symbols.outcome == 'failure' || steps.committed_smoke.outcome == 'failure')
run: exit 1


Expand Down Expand Up @@ -236,12 +230,6 @@ jobs:



- name: Verify committed macOS provenance
if: needs.changes.outputs.code == 'true'
id: committed_provenance
continue-on-error: true
run: node tooling/connect/cpp-build.mjs --verify --target aarch64-apple-darwin

- name: Check C ABI symbols
if: needs.changes.outputs.code == 'true'
id: committed_symbols
Expand Down Expand Up @@ -284,5 +272,5 @@ jobs:
retention-days: 5

- name: Fail on committed carrier errors
if: always() && (steps.committed_provenance.outcome == 'failure' || steps.committed_symbols.outcome == 'failure' || steps.committed_smoke.outcome == 'failure')
if: always() && (steps.committed_symbols.outcome == 'failure' || steps.committed_smoke.outcome == 'failure')
run: exit 1
Loading
Loading