feat(native): familiar contract and analytics reads [parked — SDK artifact reconciliation required] - #86
feat(native): familiar contract and analytics reads [parked — SDK artifact reconciliation required]#86BunsDev wants to merge 4 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The PR description indicates required conformance/contract lock re-pins are intentionally not included, so CI will remain failing until that follow-up lands.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR wires the newly promoted Cave client-v1 reads for familiar contract and analytics into Chat’s native command boundary and TypeScript SDK boundary, keeping the native command guardrails (capabilities/schema/build-script/spec-guards) in sync.
Changes:
- Add two new Tauri commands (
cave_familiar_contract,cave_familiar_analytics) plus correspondingCaveReadPathrouting/validation and analytics query-string construction. - Extend the TypeScript boundary with
QueryAdapter.familiarContract/familiarAnalytics, widenCaveReadClient, and add native transport invocations with input canonicalization. - Update capabilities/schema/build guards and vendored SDK tarball lock integrity entries.
File summaries
| File | Description |
|---|---|
| src/specification-guards.test.ts | Extends Phase 1 guard expectations to include the two new native commands/permissions. |
| src/lib/sdk/query-adapter.ts | Adds adapter methods and caching channels for familiar contract/analytics reads. |
| src/lib/sdk/query-adapter.test.ts | Adds read-client mocks for the new adapter methods. |
| src/lib/sdk/native-boundary.ts | Adds canonicalization + managed-transport methods invoking the new native commands. |
| src/lib/sdk/connection-controller.ts | Extends CaveReadClient pick to include the new read methods. |
| src/chat-shell.test.tsx | Updates test adapter stub to include the new QueryAdapter methods. |
| src/app.test.tsx | Updates test adapter stub to include the new QueryAdapter methods. |
| src-tauri/src/transport.rs | Adds CaveReadPath variants, validation, endpoint pathing, query builder, and Rust unit tests. |
| src-tauri/src/lib.rs | Exports/registers the two new commands and updates smoke-test expectations. |
| src-tauri/src/commands.rs | Implements the two new #[tauri::command] functions that route into cave_read. |
| src-tauri/gen/schemas/desktop-schema.json | Regenerates desktop schema to include allow/deny permissions for new commands. |
| src-tauri/capabilities/default.json | Adds default allow-permissions for the two new commands. |
| src-tauri/build.rs | Updates command list used for build-time guard generation. |
| pnpm-lock.yaml | Updates integrity entries for the repacked vendored SDK tarballs. |
Review details
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
- Files reviewed: 13/16 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
Added Stage 1 Task 4 on top of Task 3's native reads: the Still not included: wiring 🤖 Generated with Claude Code |
|
Added a new, separate Stage 1 shell on top of the data-source seam: I read 7 new tests (happy path, conversation switching, tab gating both ways, an all-failing source). Full local suite green — typecheck, lint, format,
🤖 Generated with Claude Code |
d32e794 to
d4e10b1
Compare
|
Split into #89, which lands the half that does not need a new SDK: the native The blocker here was that this branch replaces the vendored
The Contract canary checks out the SDK at the pinned revision and verifies the Moved to draft. Once #89 lands, rebase this onto The code itself verified clean throughout: |
|
Carrying one review finding from #89 over here, since it lands with Copilot flagged that Once |
…89) Splits #86 so the Stage 1 work that does not need a new SDK can land now. #86 replaced the vendored cave-client and sdk-core tarballs without re-pinning contract-canary.lock.json, which pins each artifact by size and SHA-256. The Contract canary checks out the SDK at the pinned revision and verifies the vendored artifacts against it, so merging that branch would have turned main's canary red. Re-pinning honestly needs a releaseManifest, which needs the authorized release cut, so the vendor bump waits. Lands here: the native familiar contract and analytics read paths, the data-source seam and its mock implementation, the capability additions, and the reads shell. Vendored artifacts and pnpm-lock.yaml are byte-identical to main. Waits for the SDK bump on #86: mappers.ts, cave-source.ts, and the familiar transport in native-boundary.ts, which between them need six symbols the pinned tarball does not export. Nothing in the app imports either module yet, so removing them cost no wiring. Also addresses the review: six tests covering the query adapter's new familiarContract and familiarAnalytics methods, and two descriptions that contradicted their code. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KacEJmkX5GhkViPUhx9Mie
Stage 1 Task 3 of the familiars integration plan (docs/superpowers/plans/2026-09-02-familiars-integration.md): add the two new Cave client-v1 reads Cave and the SDK already promoted today (coven-cave #5288, sdk #104/#105) to Chat's native command boundary. - src-tauri: two new commands, `cave_familiar_contract` and `cave_familiar_analytics`, mirroring the existing per-id read shape (`cave_get_conversation`). New `CaveReadPath::FamiliarContract`/ `::FamiliarAnalytics` variants build `/api/client/v1/familiars/:id/ {contract,analytics}`, with a `validate_canonical_familiar_id` bound matching Cave's own familiar-id charset and an analytics query builder bounded to Cave's `window`/`recent` parameters. New Rust unit tests cover id-segment encoding and out-of-bound window/recent rejection. Guard arrays (build.rs, capabilities/default.json, lib.rs, commands.rs) and the regenerated desktop schema stay in lockstep with specification-guards.test.ts. - TypeScript SDK boundary: `QueryAdapter.familiarContract`/ `familiarAnalytics` (cached like the other detail reads), `CaveReadClient` widened to the two new `CaveClient` methods, and the native transport implementation using the SDK's newly-exported `canonicalFamiliarContractData`/`canonicalFamiliarAnalyticsData` envelope helpers. - vendor/opencoven-sdk: re-packed `cave-client-0.1.0.tgz` and `sdk-core-0.1.0.tgz` from current `OpenCoven/sdk` main (commit d24b2ef), which already carries `familiarContract`/`familiarAnalytics` as unreleased changesets. Deliberately NOT included: `contract-canary.lock.json` and `phase1-conformance.lock.json` are not re-pinned to the new SDK/Cave revisions. Re-pinning requires the SDK repo's `create-release-artifacts.mjs`, which is gated by `release.config.json` `publishingEnabled: false`, and per `docs/workflows/client-v1-cross-repository-conformance.md` the whole chain is deliberately "no offline acceptance mode": a live, protected GitHub Actions environment (`client-v1-conformance`) with a named required reviewer. That re-pin needs to happen through the real protected workflow, not by hand here. Follow-up commit once that authority exists. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016ueGDYGKGaMzNq5mTE6ogG
Stage 1 Task 4 of the familiars integration plan
(docs/superpowers/plans/2026-09-02-familiars-integration.md), built on top
of the previous commit's native contract/analytics reads. Against the mock
source only -- no shell wiring here (Task 5) and no dependency on the
contract-canary lock re-pin.
- src/familiars/source.ts: the `FamiliarsSource` interface and its Stage 1
view types (`FamiliarSummary`, `FamiliarDetail` with ward/identity/
report, `FamiliarActivity`, `ConversationSummary`, `ThreadMessage`) and
the `Capability` union from the integration design's data model and
capability-gating tables.
- src/familiars/mappers.ts (+ tests): the only module that knows the shape
of a `CaveCanonicalFamiliar`, `CaveFamiliarContract`, or
`CaveExecutionWindow` -- pure functions from SDK wire types to the view
types above, tested against literal SDK-fixture-shaped objects (renames,
optional-field omission, the window-not-served and null-completion-rate
cases).
- src/familiars/cave-source.ts (+ tests): `CaveFamiliarsSource`, a thin
fetch-then-map over `QueryAdapter` (already carrying `familiarContract`/
`familiarAnalytics` from the previous commit) -- no caching or retry
logic of its own, non-ok `QueryResult`s pass straight through unmapped.
- src/familiars/mock-source.ts (+ tests): `MockFamiliarsSource` wrapping
today's `src/demo/familiars-data.ts` and `mock-familiars.ts` into the
same view types. The demo's `FamActivity` is presentation-shaped
("100%", "1m 36s") because it matches the design mockup verbatim, so
reconstructing numeric fields from it is necessarily best-effort;
reasoning/hold/image/divider messages are dropped rather than faked,
since Cave does not serve rich content, attachments, or attention items
until Stage 3/4.
- src/familiars/capabilities.ts (+ tests): `availabilityFor(control,
capabilities)`, covering every row of the design's gating table.
Not included: wiring `FamiliarsShell` to either source (Task 5), or
`ChatShell` retirement (Task 6) -- those come once Task 3's lock re-pin
unblocks a real `CaveFamiliarsSource` in production.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ueGDYGKGaMzNq5mTE6ogG
d4e10b1 to
9864c0e
Compare
|
Rebased onto `main` now that #89 has landed. This reduces to exactly the deferred remainder, as expected:
`src/familiars/source.ts`, `mock-source.ts`, and `mock-source.test.ts` conflicted against #89's already-landed (and reviewed/fixed) versions — took `main`'s version for all three per the plan, so this branch carries no diff on them anymore. `contract-canary.lock.json` still isn't re-pinned — still waiting on the authorized SDK release cut. Verified locally: typecheck clean, lint/format clean, `src/familiars/*` 46/46, full unit suite 523/525 (2 failures are the same known pre-existing environment flake in `phase1-schema-v2-evidence.test.ts`, unrelated to this diff). Still draft, still blocked on the canary re-pin — this is just housekeeping so the branch reflects exactly what's left. 🤖 Generated with Claude Code |
BunsDev
removed
the
ci:full
…here #89 landed the seam without cave-source.ts or mappers.ts, so the comment on main says one implementation exists and that the Cave-backed one arrives with the SDK bump. This branch is that bump, and it reintroduces both files, so the comment would otherwise describe as absent two modules sitting beside it. Restores the wording #89 replaced. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KacEJmkX5GhkViPUhx9Mie
|
Filed the |
Parked — blocked behind the SDK 0.1 registry releaseThis branch cannot merge for longer than previously stated here, and the reason is upstream rather than anything in the diff. The SDK source these tarballs were built from no longer exists on #109's rationale: post-freeze merges had changed publication-scoped bytes while conformance and the reviewed tarballs stayed pinned to So the vendored What has to happen first
Step 1 is now unblocked: it needs a complete win32-x64 platform record, which the Windows session-0 quarantine bug prevented until #85/#88. That job has since passed on four consecutive runs. There is no circularity in step 1, which was a concern worth checking: State of this branchRebased onto Staying open as a draft so the work is preserved. #90 tracks the one review finding that outlived it. |
BunsDev
changed the title
|
Triage update (2026-09-06): keeping this draft parked. Its upstream release gates remain open: OpenCoven/sdk#38 (cross-repository conformance), OpenCoven/sdk#40 (security ship/block decision), and OpenCoven/sdk#41 (public release). The branch is preserved; no rebase or CI rerun is useful until those gates advance. |
|
Triage refresh (2026-09-07): the upstream gate has advanced but is not cleared. OpenCoven/sdk#38 now has a passing Keeping this PR draft and intentionally not rebasing or rebuilding its vendored artifacts: they were produced from SDK symbols reverted by the 0.1 freeze, so refreshing them before those symbols are re-landed would create misleading provenance rather than mergeable work. |
Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Both new native transport methods return malformed SDK response shapes, and the required conformance locks remain stale.
Get a fresh assessment by requesting another Copilot review.
Review details
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
Suppressed comments (1)
src/lib/sdk/native-boundary.ts:677
- The analytics helper returns only
data.analytics, but this transport contract expects a response shaped as{ ok: true, analytics }. Returning the bare analytics object means the managedCaveClientsees nookoranalyticsfield and rejects successful reads. Rebuild the response envelope and cover it through the managed client.
return canonicalFamiliarAnalyticsData(result) as unknown as CaveFamiliarAnalyticsResponse;
- Files reviewed: 13/16 changed files
- Comments generated: 1
- Review effort level: Balanced
| }, | ||
| context, | ||
| ); | ||
| return canonicalFamiliarContractData(result) as unknown as CaveFamiliarContractResponse; |
BunsDev
changed the title
Current checkpoint: SDK #262's decoder repair is landed, but it has not been adopted into frozen candidate
96804bc483a063e41e9a9738a4ace61970f6c0a4. Reconcile this PR's feature and 0.1.0 vendor archives against the reviewed candidate and current main before considering readiness. The first-release planning target is 0.0.1; existing archives must not be relabeled.The preceding protected run
35111662551used Chat #297 (43504f646e7ffe01ee6019d468401f99be839420) and SDK #290 (ca3f4ed1ab7f5732ff51e30c29ddbcab529eee0e). Linux and macOS records independently passed identity, timing, privacy and all 197 ordered assertions each. Windows failed atphase1.stage.evidence-authority.isolation.failed, published no record, and downstream validation/attestation/aggregation were skipped.Chat #305 then landed bounded isolation diagnostics at
1f69306293f8caf873e0a2d6459a5c402e77600a, followed by SDK #291 at404c2bf898330cff10e0402646e83e6e65d17869. Both validator scopes were rotated/read back at that SDK delivery. Protected run 35125287541, attempt 1, is now terminal: Linux and macOS records independently passed identity, timing, privacy and all 197 ordered assertions each. Windows failed atphase1.stage.execution-root-cleanup.failed, emitted no platform record, and downstream validation, aggregation and attestation were skipped. Execution-root cleanup precedes isolation validation, so this result does not establish that the prior isolation failure is repaired. The next investigation is bounded classification of the actual cleanup operation, preserving containment, cleanup ordering and existing limits.None of these runs validates this draft's unchanged head or adopts its 0.1.0 vendor archives. The decoder repair still requires deliberate candidate/artifact reconciliation before this feature can land. Follow SDK #38 for protected acceptance and Chat #219 for the Windows investigation. The familiar-source worktree and distinct local commits remain preserved.
Adds a Cave-backed
FamiliarsSourceover the existing query adapter, with wire-to-view mappers for familiar details, activity, conversations, and messages. The native managed transport gains bounded familiar contract and analytics calls. Focused source/mapper tests accompany the change.The current diff also changes SDK 0.1.0 vendor archives, dependency locks, conformance manifest/artifact hashes, and associated tests and documentation. These supply-chain changes need reconciliation with current main before landing; the earlier description that the conformance locks were untouched was stale.
This remains a parked draft. Protected run 34849881134 completed using private SDK candidate
96804bc483a063e41e9a9738a4ace61970f6c0a4, Chat producer535d48196d96a4fde39cd62c47ccec2307a5b3d6and SDK validator118b3da46d9b91608272d242918237b1cacc9943. Linux and macOS records passed independent inspection; Windows failed before Cave readiness and emitted no platform record. Aggregate validation and attestation were skipped. That run does not validate this PR's head or its 0.1.0 archives. SDK publication remains disabled.The missing canonical familiar decoders and dropped contract/analytics fields are addressed by merged SDK #262. All eight checks passed on corrected head
afe974e400cda09238c6cf318fa375bea08c1220; signed mergec9eb736ec30543d63115d3675e7b10863c08796fhas the verified clean integration tree. The corrected SDK tarballs also passed all 48 targeted Chat boundary/source/mapper tests and the full Chat typecheck in the isolated reconciliation worktree. Those checks do not adopt the landed SDK as the frozen candidate. In the isolated Chat reconciliation worktree, two native-boundary regressions failed against the frozen SDK and all 48 targeted boundary/source/mapper tests passed against extracted repaired SDK tarballs. This is integration evidence for the reconciliation work, not verification of this PR's unchanged remote head or acceptance of new frozen artifacts.Before landing:
The earlier local test counts described a previous state and are not fresh verification of head
122075559361f6d0f056ab29eebdccdb9a22ce23. The active familiar-source worktree is preserved.