Foundation contracts for portable jarvOS product realization

capability-ledger.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": "jarvos.capability-ledger.v1",
+  "records": [
+    {
+      "capabilityId": "portable-identity",
+      "title": "Portable opaque identity contract",
+      "specification": "draft",
+      "implementation": "partial",
+      "repository": "draft-pr",
+      "verification": "fixture-proven",
+      "activation": "inactive",
+      "authority": "none",
+      "evidence": [
+        { "type": "repo-path", "ref": "modules/jarvos-control-plane/src/identity.js" },
+        { "type": "test", "ref": "modules/jarvos-control-plane/test/identity.test.js" },
+        { "type": "document", "ref": "docs/architecture/capability-truth-ledger.md" },
+        { "type": "pull-request", "ref": "pull/257" }
+      ],
+      "assertedOn": "2026-08-31",
+      "notes": "Draft-PR validator, exports, and unit tests exist; no product consumer issues identifiers yet."
+    },
+    {
+      "capabilityId": "capability-truth-ledger",
+      "title": "Capability truth ledger contract",
+      "specification": "draft",
+      "implementation": "partial",
+      "repository": "draft-pr",
+      "verification": "fixture-proven",
+      "activation": "inactive",
+      "authority": "none",
+      "evidence": [
+        { "type": "repo-path", "ref": "scripts/lib/capability-ledger.js" },
+        { "type": "document", "ref": "docs/architecture/capability-truth-ledger.md" },
+        { "type": "repo-path", "ref": "capability-ledger.json" },
+        { "type": "pull-request", "ref": "pull/257" }
+      ],
+      "assertedOn": "2026-08-31",
+      "notes": "This draft-PR ledger validates against its own contract; no automated reporter consumes it yet."
+    },
+    {
+      "capabilityId": "candidate-envelope",
+      "title": "Non-authoritative candidate envelope contract",
+      "specification": "draft",
+      "implementation": "partial",
+      "repository": "draft-pr",
+      "verification": "fixture-proven",
+      "activation": "inactive",
+      "authority": "none",
+      "evidence": [
+        { "type": "repo-path", "ref": "modules/jarvos-secondbrain/packages/jarvos-ambient/src/intent/candidate-contract.js" },
+        { "type": "test", "ref": "modules/jarvos-secondbrain/packages/jarvos-ambient/test/candidate-contract.test.js" },
+        { "type": "document", "ref": "modules/jarvos-secondbrain/docs/contracts/CANDIDATE_ENVELOPE.md" },
+        { "type": "test", "ref": "tests/fixtures/foundation-contracts/manifest.json" },
+        { "type": "pull-request", "ref": "pull/257" }
+      ],
+      "assertedOn": "2026-08-31",
+      "notes": "Draft-PR validator, exports, unit tests, and shared conformance fixtures exist; no source adapter or promotion consumer constructs candidates yet."
+    },
+    {
+      "capabilityId": "promotion-receipt",
+      "title": "Cross-surface promotion receipt envelope contract",
+      "specification": "draft",
+      "implementation": "partial",
+      "repository": "draft-pr",
+      "verification": "fixture-proven",
+      "activation": "inactive",
+      "authority": "none",
+      "evidence": [
+        { "type": "repo-path", "ref": "modules/jarvos-control-plane/src/promotion-receipt.js" },
+        { "type": "test", "ref": "modules/jarvos-control-plane/test/promotion-receipt.test.js" },
+        { "type": "document", "ref": "modules/jarvos-control-plane/README.md" },
+        { "type": "test", "ref": "tests/fixtures/foundation-contracts/manifest.json" },
+        { "type": "pull-request", "ref": "pull/257" }
+      ],
+      "assertedOn": "2026-08-31",
+      "notes": "Draft-PR validator, exports, unit tests, and shared conformance fixtures exist; no destination writer emits this envelope yet."
+    }
+  ]
+}

docs/architecture/capability-truth-ledger.md

@@ -0,0 +1,63 @@
+# Capability truth ledger
+
+The capability truth ledger is repository truth tooling. It records what the
+project asserts about each capability and points to the evidence behind the
+assertion. It is not discovery, not an activation probe, and not proof that a
+capability runs anywhere. Reading the ledger tells you what has been claimed and
+where to check it; validating it inspects no repository, host, process, or
+network. In particular, a record on an open draft pull request is a draft
+specification and `draft-pr` repository state, never canonical or
+repository-shipped merely because its branch contains code and tests.
+
+## Schema
+
+A ledger is `{ schemaVersion, records }` with schema version
+`jarvos.capability-ledger.v1`. Unknown schema versions, unknown enum values, and
+unknown fields fail closed at both the top level and inside each record.
+
+## Independent truth dimensions
+
+Each record carries six independent dimensions. A capability can be strong on
+one and absent on another, so the validator never derives one from another:
+
+| Dimension | States |
+| --- | --- |
+| `specification` | `absent`, `draft`, `canonical` |
+| `implementation` | `absent`, `partial`, `complete` |
+| `repository` | `local-only`, `draft-pr`, `merged`, `released` |
+| `verification` | `untested`, `fixture-proven`, `clean-install-proven`, `live-canary-proven` |
+| `activation` | `inactive`, `test-fixture`, `disposable`, `enrolled-host`, `production`, `unknown` |
+| `authority` | `none`, `read-only`, `proposed`, `active`, `conflicted` |
+
+The activation vocabulary is generic public-product language. It never names a
+specific operator's machines.
+
+## Records and evidence
+
+Every record also has a bounded lowercase `capabilityId`, a bounded `title`, an
+ISO `assertedOn` date, optional bounded `notes`, and a non-empty `evidence`
+array. Each evidence pointer is `{ type, ref }`, where type is `repo-path`,
+`pull-request`, `test`, `document`, or `commit`. A reference is a bounded,
+repository-relative pointer, except that a pull-request pointer is a bounded
+tracker-relative reference such as `pull/257`; it cannot be absolute, cannot
+contain `..` traversal, and cannot carry a `file:` or other URI scheme.
+
+## Invariants
+
+- Duplicate capability IDs fail.
+- The six dimensions stay independent.
+- Evidence references stay relative and scheme-free.
+- The validator performs no I/O; it only checks shape and bounds.
+- The ledger is an assertion set. A record is a claim with evidence pointers,
+  not a discovered fact and not an activation proof.
+
+## Seed ledger
+
+The tracked `capability-ledger.json` seed describes only the foundation work in
+draft pull request 257. Its identity, truth-ledger, candidate-envelope, and
+promotion-receipt contracts are asserted at `specification: draft`,
+`implementation: partial`, and `verification: fixture-proven` because their
+validators and tests exist but no installed product consumer activates them.
+Every seed record is `repository: draft-pr`, `activation: inactive`, and
+`authority: none`. Merge and release are separate future observations; neither
+is inferred from this branch.

docs/architecture/product-category-and-boundaries.md

@@ -1,7 +1,7 @@
 ---
 status: active
 created: 2026-05-17
-updated: 2026-05-17
+updated: 2026-08-31
 canonical: true
 type: architecture
 ---
@@ -43,6 +43,68 @@ The runtime owns model calls, shell execution, sandboxing, scheduling,
 messaging, and tool orchestration. jarvOS owns the user-controlled context and
 operating contract those runtimes hydrate from and write back to.
 
+## Runtime modes and ownership
+
+jarvOS has no load-bearing harness. A compatible runtime is one optional way
+to host a jarvOS interaction, never the permanent owner of the product's
+identity, context, or governance contract. Runtime modes are intentionally
+parallel:
+
+- **Native runtime mode:** a harness runs its own model, tools, scheduling,
+  delivery, and native session lifecycle. Native session identifiers and their
+  storage remain harness-owned.
+- **jarvOS service mode:** jarvOS-owned services provide portable context,
+  policy, candidate, and receipt boundaries to compatible callers. Active
+  Assistant is a jarvOS-owned service boundary in this mode; it is not the
+  load-bearing owner of a particular harness.
+- **Compatibility-read mode:** a harness may read compatible jarvOS context
+  through an adapter or documented file/API contract. The read direction is
+  from jarvOS-owned portable context to the harness; it does not import a
+  harness's private session state, require a harness to be installed, or grant
+  jarvOS ownership of native sessions.
+
+Portable conversation identity, explicit mappings from native sessions where a
+harness safely exposes them, and cross-surface promotion receipts remain
+jarvOS-owned contracts. A mapping is metadata, not a takeover: it cannot mint,
+rename, replay, or infer a native session identity.
+
+Conformance is tiered so an adapter cannot borrow confidence from another
+harness: contract/fixture conformance proves portable shape; adapter
+conformance proves a named compatibility reader; and installed or live proof,
+when a future adapter elects to provide it, proves only that named adapter.
+The current foundation provides contract/fixture conformance only. It does not
+claim adapter, installed, or live behavior.
+
+## Product Realization Boundary
+
+The product architecture permits a future adapter to observe eligible AI
+interactions and prepare bounded, source-backed candidates for notes, journals,
+memory, ontology, Projects, skills, or work. That future path could help
+construct a useful digital twin across harnesses without treating every
+transcript or model statement as true. This draft foundation implements no
+source adapter, candidate storage, or promotion consumer.
+
+The boundary is explicit:
+
+- portable identities connect a mind, its installations, harness sessions,
+  source events, candidates, artifacts, policies, Projects, and receipts
+  without making one machine the permanent home of jarvOS;
+- an asserted candidate is immutable and non-authoritative, contains evidence
+  pointers rather than raw source content, and cannot claim completion,
+  verification, destination state, or Project identity;
+- promotion into authoritative memory, ontology, Projects, authored notes, or
+  other durable surfaces is governed by the owning writer and policy;
+- a promotion receipt distinguishes a committed destination revision from an
+  already-satisfied, deferred, conflicted, or failed attempt and does not
+  promise universal rollback; and
+- the capability truth ledger keeps specification, implementation, repository,
+  verification, activation, and authority state independent, so code or
+  documentation cannot masquerade as a live working capability.
+
+This is one mind across many harnesses, not one runtime controlling every
+harness. Runtime-specific capabilities remain adapters behind portable jarvOS
+contracts.
+
 ## Guardrails
 
 - Runtime adapters are replaceable glue, not the product core.

docs/architecture/secondbrain-external-integrations.md

@@ -97,17 +97,36 @@ match. Missing or incompatible private fields produce `unknown`; the global
 
 ## Operating Model
 
-The active secondbrain path is:
+The intended secondbrain model is below. Only intentional capture is active in
+this repository today; the eligible-interaction candidate stages are future
+adapter behavior.
 
 ```text
 intentional capture
   -> Obsidian-compatible Markdown Notes/Journal
+
+future eligible AI interactions
+  -> eligibility and trust boundary
+  -> immutable, source-backed, non-authoritative candidates
+  -> governed review or policy admission
+  -> destination-owned promotion plus outcome receipt
+
+authoritative durable surfaces
   -> source-backed sidecars and generated LLM-wiki
   -> QMD freshness / broad lookup
   -> GBrain curated structured recall
   -> OpenClaw memory-wiki and runtime recall diagnostics
 ```
 
+Intentional capture remains the direct authored path. Eligible ambient
+observation is a future proposal path: a future adapter may prepare candidates,
+but this foundation contains no source adapter that does so. It does not
+automatically believe, promote, or retain every conversation. Source
+trust, privacy, expiry, deduplication, and evidence binding are checked before
+candidate construction. Destination owners still decide admission and emit a
+receipt whose outcome distinguishes a committed revision from a failed,
+deferred, conflicted, or already-satisfied attempt.
+
 Paperclip runs alongside that path for execution state. It records issues,
 owners, blockers, reviews, release evidence, and follow-up work, but it is not
 the knowledge base.
@@ -147,7 +166,10 @@ Active integrations should be proven through these public-safe signals:
 
 ## Non-Goals
 
-- No automatic ingestion of every AI conversation.
+- No indiscriminate ingestion of every AI conversation, raw transcript
+  hoarding, or automatic belief. A future eligible-interaction adapter may
+  produce bounded non-authoritative candidates; durable promotion remains
+  governed.
 - No ChatGPT or Claude app first-class capture target in the current
   determinism contract.
 - No direct agentmemory host access or automatic memory promotion.