Continuity Format

Raw markdown: /continuity-format/published.md. This page is readable without a session.

**Version:** 0.1.0  
**Status:** published interchange specification  
**Canonical package:** `@zephr-ai/continuity-format` `0.1.0` (this document's version **is** that semver)  
**Stable URL:** `https://zephr.ai/continuity-format`  
**Raw text:** `https://zephr.ai/continuity-format/published.md`

This is the open specification for Continuity Format v1 (`format: "zephr-continuity"`, `formatVersion: 1`). An independent producer or consumer can implement it from this document alone. A Zephr account, Zephr service, Zephr SDK, or any `x-zephr-*` extension is **not** required to produce, validate, ingest, or emit a transfer receipt for a conforming packet.

Copyright 2026 Digital Soft Distribution / Zephr contributors.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this specification except in compliance with the License. You may obtain a copy at:

<http://www.apache.org/licenses/LICENSE-2.0>

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

**Grant.** This specification and its publication golden vectors are licensed Apache-2.0. You may implement producers and consumers — including commercial, closed-source, and competing products — without a Zephr account, without a trademark licence, and without copyleft infection of your code. The name "Zephr" is not licensed for use as a product name or endorsement. Patent peace follows Apache-2.0 §3.

The `@zephr-ai/continuity-format` TypeScript package remains a private reference implementation. Using it is optional. Conformance is defined by this document and the publication golden vectors, not by importing that package.

Zephr constitution constraint 15: **no AGPL or CC-BY-NC in the continuity data path.** A conforming implementation MUST NOT introduce AGPL, CC-BY-NC, SSPL, BUSL, or Unlicensed components on the packet validate / ingest / receipt path. Apache-2.0, MIT, BSD, ISC, and PostgreSQL-Licence are acceptable. This constraint is about _runtime dependencies of the interchange path_, not about the licence of this specification (which is Apache-2.0).

| Field                     | Rule                                                                                                                                     |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `format`                  | Constant `"zephr-continuity"`.                                                                                                           |
| `formatVersion`           | Integer major. This document describes `1`. A new major is a breaking envelope change.                                                   |
| Document / package semver | `0.1.0` today. Patch = editorial. Minor = additive optional fields (v1.1 `scopeProof` style). Major = `formatVersion` bump.              |
| Additive fields           | Optional. Absence MUST remain valid for the same `formatVersion`.                                                                        |
| Unknown top-level fields  | MUST be rejected by a v1 validator (closed field set).                                                                                   |
| `extensions`              | Required object. May be `{}`. Keys MUST NOT be required for a packet to validate. Publication goldens MUST NOT contain `x-zephr-*` keys. |

A v1 packet is a single JSON object with exactly these keys (plus optional `scopeProof`):

| Field                     | Required | Meaning                                                                                   |
| ------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `format`                  | yes      | `"zephr-continuity"`                                                                      |
| `formatVersion`           | yes      | `1`                                                                                       |
| `artifactKind`            | yes      | `"session-handoff"` or `"continuity-archive"`                                             |
| `canonicalizationProfile` | yes      | `"ZCF-JSON-v1"`                                                                           |
| `packet`                  | yes      | Packet identity (id, nonce, intent, timestamps, `generation: 1`)                          |
| `source`                  | yes      | Installation key id, scope refs, client descriptor                                        |
| `recipientIntent`         | yes      | `"unbound-local-import"` or `"recipient-bound"`                                           |
| `content`                 | yes      | Archive refs **or** session-handoff sections                                              |
| `redactionManifest`       | yes      | Policy id/version + entries (may be empty)                                                |
| `omissionManifest`        | yes      | Entries (may be empty)                                                                    |
| `retention`               | yes      | Export timestamp, policy version, review-by, optional expiry                              |
| `manifest`                | yes      | Domain-separated LP SHA-256 root over canonical sections                                  |
| `authentication`          | yes      | `"unsigned"`, `"recipient-bound-mac"`, or `"source-signature"` (see Authentication kinds) |
| `extensions`              | yes      | Object; `{}` is the third-party default                                                   |
| `scopeProof`              | no       | v1.1 additive admission proof                                                             |

`source.client.kind` is one of: `claude-code`, `cursor`, `codex`, `opencode`, `console`. These name **hosts**, not a Zephr vendor lock. A third-party tool that is not Zephr still uses one of these host kinds (or waits for an additive kind in a later minor).

Unsigned packets (`authentication.kind === "unsigned"`) are valid structural packets. Cryptographic authentication is optional for publication conformance. A destination MAY refuse unsigned packets as a local policy; that is not a format requirement.

### Authentication kinds

`authentication.kind` is one of:

| Kind                  | Meaning                                                                                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `unsigned`            | No cryptographic authentication. Valid structural packet.                                                                                                    |
| `recipient-bound-mac` | Ed25519 source signature + recipient-bound HMAC-SHA-256 (HKDF). Verifiable when the destination holds the source public key and both installation key bytes. |
| `source-signature`    | A bare Ed25519 source signature (`signature`, `algorithm`, `publicKeyFingerprint`) with **no** recipient-bound HMAC.                                         |

A `source-signature` packet carries no recipient-bound HMAC and no public-key trust input in the conformance options, so a conforming verifier **MUST NOT** accept it as verified. It MUST be refused with the distinct code `source_signature_unverifiable` — never silently treated as `unsigned`, and never accepted on the strength of the embedded `publicKeyFingerprint` alone (a fingerprint is a claim, not a trust anchor).

These are the stable **section** names a producer fills and a consumer reads. A section that cannot be captured is recorded on `omissionManifest` — never silently dropped.

### Session-handoff content sections

| Section           | Role                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `capsule`         | Session objective, decisions, constraints, changed files, risks, questions, next actions, capture quality, limitations, lifecycle coverage |
| `beliefs`         | Portable memory items (`portableRef`, `sourceId`, `content`, optional `reviewState`)                                                       |
| `evidenceSources` | External or local sources the capsule cites                                                                                                |
| `evidenceAnchors` | Bindings from claims to source material                                                                                                    |
| `receipts`        | Patch / verification receipts the capsule cites                                                                                            |
| `reviewEvents`    | Human review events (may be empty)                                                                                                         |
| `verification`    | Verification artefacts (may be empty)                                                                                                      |
| `sourceHandoff`   | From/to session ids, worktree id, checkpoint belief ids                                                                                    |
| `allowedTools`    | Optional closed tool-name list for the destination contract                                                                                |

### Envelope-level sections (in the integrity manifest)

| Section            | Role                                    |
| ------------------ | --------------------------------------- |
| `packetIdentity`   | `packet` object                         |
| `sourceDescriptor` | `source` object                         |
| `recipientIntent`  | Recipient binding                       |
| `retention`        | Retention / review-by metadata          |
| `scopeProof`       | Present only when the v1.1 field is set |

A destination declares **capabilities** as the tool names it can honour. The published closed set is:

| Capability       | Meaning                                   |
| ---------------- | ----------------------------------------- |
| `zephr_remember` | Persist an admitted belief                |
| `zephr_recall`   | Retrieve admitted beliefs                 |
| `zephr_why`      | Explain a belief from evidence            |
| `zephr_verify`   | Run a verification step                   |
| `zephr_session`  | Read session / handoff metadata           |
| `zephr_rules`    | Read or apply workspace rules (high-risk) |
| `zephr_status`   | Read runtime / admission status           |
| `zephr_admin`    | Administrative mutation (high-risk)       |

Names are historical (`zephr_*`) and are **identifiers in this format**, not a requirement to run Zephr. An independent consumer maps them onto its own tools. A packet with no `allowedTools` does not constrain the destination. High-risk residue (`zephr_admin`, `zephr_rules`) may be refused in strict mode or degraded otherwise — never silently honoured.

When a destination cannot honour a section or tool contract, it MUST pick exactly one of these statuses (and record it — no silent drop):

| Status         | Meaning                                                                 |
| -------------- | ----------------------------------------------------------------------- |
| `native`       | Section / tool applied as-is                                            |
| `narrated`     | Content kept as prose / note; original action not executed              |
| `dropped`      | Explicitly omitted; listed on the transfer receipt or omission manifest |
| `refused`      | Import aborted (strict contract or policy)                              |
| `omitted`      | Source never captured the section (`omissionManifest`)                  |
| `unsupported`  | Destination does not implement the section                              |
| `not_captured` | Source attempted capture and failed                                     |
| `redacted`     | Present at source, removed under a redaction policy                     |

Capture quality on the capsule is one of `complete` | `partial` | `degraded`. Lifecycle coverage is one of `native` | `consented-manual` | `derived` | `unavailable`.

Review state on a portable belief is one of `unreviewed` | `confirmed` | `rejected` | `superseded`. A foreign or third-party packet MUST NOT arrive as `confirmed` unless a human at the **destination** later attests it. Independent importers write `unreviewed`.

`manifest.rootHash` is `sha256:` plus hex of a domain-separated, length-prefixed SHA-256 over the canonical JSON of each covered section. Domain string: `zephr-continuity-manifest-v1`. Section keys are sorted by Unicode code point. A validator MUST recompute the root and reject `manifest_root_mismatch`.

Canonicalization profile `ZCF-JSON-v1`: UTF-8 JSON, object keys sorted, no insignificant whitespace, `-0` normalised to `0`, integers without a trailing `.0`.

A successful ingest of a publication-conforming packet MUST yield a **transfer receipt** with at least:

- `packetId`, `packetNonce`
- `sourceInstallationKeyId`
- `destinationInstallationKeyId` (`unbound` when `recipientIntent.kind` is `unbound-local-import`)
- `targetDigest`, `manifestRootHash`
- `correlationId` (destination-computed, not trusted from the packet)
- `importedAt`
- counts: `demotionCount`, `degradationCount`, `truncatedBeliefCount`
- `receiptDigest` (hash of the signed draft)

Unsigned third-party packets use a destination-local authenticate-before-parse step that validates structure and manifest integrity, then emits this receipt. Cryptographic source identity is optional.

Checked-in vectors under `packages/continuity-format/goldens/publication/` are the conformance suite:

1. Every golden MUST validate as a v1 envelope.
2. Every golden MUST ingest and produce a transfer receipt.
3. Every golden MUST be free of `x-zephr-*` keys. A vector that requires a Zephr-only extension is **not** a publication golden — CI fails if one is added.

Run: `node scripts/check-continuity-goldens.mjs` (folded into the existing `ci` job).

- Not a claim that using this format makes a product legally compliant with any regulation.
- Not a trademark licence.
- Not a requirement to use Zephr software.
- Not an invitation to put AGPL or CC-BY-NC on the validate/ingest path.