@cleocode/core 2026.9.20 → 2026.9.22

package/dist/cloud/manifest-check.js

@@ -0,0 +1,70 @@
+/** Sum the per-table deltas of every segment folded into a checkpoint. */
+export function sumDeltas(deltas) {
+    const out = {};
+    for (const d of deltas) {
+        for (const [table, { created, deleted }] of Object.entries(d)) {
+            const prev = out[table] ?? { created: 0, deleted: 0 };
+            out[table] = { created: prev.created + created, deleted: prev.deleted + deleted };
+        }
+    }
+    return out;
+}
+/**
+ * Decide whether a new checkpoint manifest may replace its parent.
+ *
+ * The rule is exact, not a heuristic: for every table,
+ * `next.rows === parent.rows + created - deleted`, summed over the segments between the two
+ * checkpoints. Every shrink therefore needs a tombstone op to back it. A table present in the
+ * parent must still be present, even with 0 rows.
+ *
+ * With no parent (genesis), only the schema version is checked.
+ */
+export function checkManifest(parent, next, between, maxAcceptedSchemaVersion) {
+    if (next.schemaVersion > maxAcceptedSchemaVersion) {
+        return {
+            ok: false,
+            code: 'E_SCHEMA_AHEAD',
+            schemaVersion: next.schemaVersion,
+            maxAccepted: maxAcceptedSchemaVersion,
+        };
+    }
+    if (parent === null)
+        return { ok: true };
+    const findings = [];
+    const tables = new Set([...Object.keys(parent.tables), ...Object.keys(between)]);
+    for (const table of tables) {
+        const parentRows = parent.tables[table]?.rows ?? 0;
+        const { created, deleted } = between[table] ?? { created: 0, deleted: 0 };
+        const expectedRows = parentRows + created - deleted;
+        const entry = next.tables[table];
+        if (entry === undefined) {
+            if (parentRows > 0 || expectedRows > 0) {
+                findings.push({
+                    table,
+                    parentRows,
+                    created,
+                    deleted,
+                    expectedRows,
+                    actualRows: 0,
+                    reason: 'missing-table',
+                });
+            }
+            continue;
+        }
+        if (entry.rows !== expectedRows) {
+            findings.push({
+                table,
+                parentRows,
+                created,
+                deleted,
+                expectedRows,
+                actualRows: entry.rows,
+                reason: 'count-mismatch',
+            });
+        }
+    }
+    return findings.length === 0
+        ? { ok: true }
+        : { ok: false, code: 'E_REGRESSION', tables: findings };
+}
+//# sourceMappingURL=manifest-check.js.map

package/dist/cloud/manifest-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-check.js","sourceRoot":"","sources":["../../src/cloud/manifest-check.ts"],"names":[],"mappings":"AAiBA,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,MAA8B;IACtD,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YACtD,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,CAAC;QACpF,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAuB,EACvB,IAAc,EACd,OAAoB,EACpB,wBAAgC;IAEhC,IAAI,IAAI,CAAC,aAAa,GAAG,wBAAwB,EAAE,CAAC;QAClD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,gBAAgB;YACtB,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,WAAW,EAAE,wBAAwB;SACtC,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAEzC,MAAM,QAAQ,GAAwB,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACjF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;QACnD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC1E,MAAM,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,UAAU,GAAG,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;gBACvC,QAAQ,CAAC,IAAI,CAAC;oBACZ,KAAK;oBACL,UAAU;oBACV,OAAO;oBACP,OAAO;oBACP,YAAY;oBACZ,UAAU,EAAE,CAAC;oBACb,MAAM,EAAE,eAAe;iBACxB,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK;gBACL,UAAU;gBACV,OAAO;gBACP,OAAO;gBACP,YAAY;gBACZ,UAAU,EAAE,KAAK,CAAC,IAAI;gBACtB,MAAM,EAAE,gBAAgB;aACzB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC;QAC1B,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE;QACd,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC5D,CAAC"}

package/dist/cloud/projects.d.ts

@@ -0,0 +1,13 @@
+import { type Project, type RegisterProjectRequest, type StreamId } from '@cleocode/contracts/cloud';
+import type { Http } from './http.js';
+/**
+ * Register a project, or update its metadata when it is already registered. Organizations own
+ * projects (ADR-095): pass `organizationId` to register into one the caller belongs to, or omit it
+ * for the caller's personal organization. Re-registering into a different organization is refused
+ * with `E_CONFLICT`. The server records no filesystem path.
+ */
+export declare function registerProject(http: Http, req: RegisterProjectRequest): Promise<{
+    project: Project;
+    streamId: StreamId;
+}>;
+//# sourceMappingURL=projects.d.ts.map

package/dist/cloud/projects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/cloud/projects.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,sBAAsB,EAE3B,KAAK,QAAQ,EACd,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,CAEnD"}

package/dist/cloud/projects.js

@@ -0,0 +1,11 @@
+import { RegisterProjectResult, } from '@cleocode/contracts/cloud';
+/**
+ * Register a project, or update its metadata when it is already registered. Organizations own
+ * projects (ADR-095): pass `organizationId` to register into one the caller belongs to, or omit it
+ * for the caller's personal organization. Re-registering into a different organization is refused
+ * with `E_CONFLICT`. The server records no filesystem path.
+ */
+export async function registerProject(http, req) {
+    return http.request('POST', '/v1/projects', RegisterProjectResult, req);
+}
+//# sourceMappingURL=projects.js.map

package/dist/cloud/projects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../src/cloud/projects.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AAGnC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,GAA2B;IAE3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,qBAAqB,EAAE,GAAG,CAAC,CAAC;AAC1E,CAAC"}

package/dist/cloud/signing.d.ts

@@ -0,0 +1,105 @@
+import type { Manifest, ReplicaHeads, RevocationPins, TableDeltas } from '@cleocode/contracts/cloud';
+/** The metadata a segment carries in plaintext beside its ciphertext. */
+export interface SegmentMetaFields {
+    schemaVersion: number;
+    opCount: number;
+    hlcMin: string;
+    hlcMax: string;
+    deltas: TableDeltas;
+}
+/**
+ * Canonical JSON of a segment's plaintext metadata: keys sorted at every level, only the listed fields.
+ * Its sha256 (the "meta hash") is covered by the segment signature and by the ciphertext's AAD, so the
+ * server cannot change a count, an HLC or a delta without the client noticing. Table names are never
+ * integer-like (they start with a letter), so JSON.stringify keeps the sorted insertion order.
+ */
+export declare function segmentMetaCanonical(m: SegmentMetaFields): string;
+/**
+ * The bytes a device signs (Ed25519) for a journal segment, v2. It binds the ciphertext hash and the
+ * metadata hash to the stream, the replica, the signing device and the replica's position, so a valid
+ * segment cannot be replayed into another stream or position, claimed for another device's replica, or
+ * served with forged metadata.
+ */
+export declare function segmentSigningMessage(parts: {
+    streamId: string;
+    replicaId: string;
+    deviceId: string;
+    replicaSeq: number;
+    segmentHash: string;
+    metaHash: string;
+}): Uint8Array;
+/** Canonical JSON of a checkpoint manifest: keys sorted at every level. */
+export declare function manifestCanonical(m: Manifest): string;
+/** Canonical JSON of a checkpoint's replica map: replica ids sorted, then `deviceId`, `lastReplicaSeq`. */
+export declare function replicasCanonical(r: ReplicaHeads): string;
+/** Canonical JSON of revocation pins: `checkpoints` then `replicas`, each with sorted keys. */
+export declare function revocationPinsCanonical(p: RevocationPins): string;
+/** The fields a checkpoint signature covers, in message order. */
+export interface CheckpointSigningParts {
+    streamId: string;
+    checkpointId: string;
+    parentCheckpointId: string | null;
+    replicaId: string;
+    deviceId: string;
+    coversSeq: number;
+    manifestHash: string;
+    /** sha256 hex of replicasCanonical(replicas). */
+    replicasHash: string;
+    blobSha256: string;
+    sizeBytes: number;
+}
+/**
+ * The bytes the authoring device signs (Ed25519) for a checkpoint, v2. `parentCheckpointId` is `-` for
+ * a genesis checkpoint. A client verifies this before restoring, so an older checkpoint cannot be served
+ * under a newer id, a record's fields cannot be edited, and the replica map that seeds the pull cursor
+ * is the author's.
+ */
+export declare function checkpointSigningMessage(parts: CheckpointSigningParts): Uint8Array;
+/**
+ * The bytes another device signs to endorse (re-sign) a checkpoint: the same fields, under their own
+ * domain and the endorser's id, so an endorsement is never mistaken for an authorship.
+ */
+export declare function checkpointEndorsementMessage(endorserDeviceId: string, parts: CheckpointSigningParts): Uint8Array;
+/**
+ * The bytes a certified device signs to revoke one signing key of a device and pin its history.
+ */
+export declare function deviceRevocationMessage(parts: {
+    userId: string;
+    revokedDeviceId: string;
+    /** Hex of the raw 32-byte Ed25519 public key being revoked. */
+    revokedSigningPublicKeyHex: string;
+    /** sha256 hex of revocationPinsCanonical(pins). */
+    pinsHash: string;
+    signerDeviceId: string;
+}): Uint8Array;
+/**
+ * The bytes a device certificate MACs: HMAC-SHA256 keyed by HKDF(masterKey, "device-cert"). It binds a
+ * device's public keys to the user and a master key version. Only a master key holder can make one.
+ */
+export declare function deviceCertificateMessage(parts: {
+    userId: string;
+    deviceId: string;
+    /** Hex of the raw 32-byte X25519 public key. */
+    encryptionPublicKeyHex: string;
+    /** Hex of the raw 32-byte Ed25519 public key. */
+    signingPublicKeyHex: string;
+    keyVersion: number;
+}): Uint8Array;
+/**
+ * The bytes the granting device signs (Ed25519) for a device key grant. It covers the recipient and
+ * its keys, the key version, the sealed box (by hash) and the recipient's certificate, and names the
+ * signer, so the grant can be neither redirected nor re-attributed.
+ */
+export declare function deviceGrantMessage(parts: {
+    userId: string;
+    recipientDeviceId: string;
+    recipientEncryptionPublicKeyHex: string;
+    recipientSigningPublicKeyHex: string;
+    keyVersion: number;
+    /** sha256 hex of the raw sealed-box bytes. */
+    sealedMasterKeyHash: string;
+    /** Hex of the raw certificate bytes. */
+    certificateHex: string;
+    signerDeviceId: string;
+}): Uint8Array;
+//# sourceMappingURL=signing.d.ts.map

package/dist/cloud/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../src/cloud/signing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAenC,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;CACrB;AAYD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAQjE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,UAAU,CAUb;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAYrD;AASD,2GAA2G;AAC3G,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAIzD;AAED,+FAA+F;AAC/F,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAKjE;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAeD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,sBAAsB,GAAG,UAAU,CAElF;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,sBAAsB,GAC5B,UAAU,CAMZ;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,0BAA0B,EAAE,MAAM,CAAC;IACnC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,UAAU,CASb;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iDAAiD;IACjD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,UAAU,CASb;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+BAA+B,EAAE,MAAM,CAAC;IACxC,4BAA4B,EAAE,MAAM,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,UAAU,CAYb"}

package/dist/cloud/signing.js

@@ -0,0 +1,117 @@
+/*
+ * The exact bytes every signature and MAC in the E2E protocol covers (docs/security/e2e-keys.md).
+ * Each message starts with its own domain string, so a signature made for one purpose never verifies
+ * for another. Hashes are lowercase hex sha256; public keys and other binary values are lowercase hex of
+ * their raw bytes, so two base64 spellings of one key cannot yield two messages.
+ *
+ * Hashing is left to the caller (node:crypto), which keeps these helpers identical to the cleo-nexus copy
+ * (packages/shared/src/signing.ts). Always hash the UTF-8 bytes of the canonical strings below.
+ */
+const enc = new TextEncoder();
+const lines = (...parts) => enc.encode(parts.join('\n'));
+const sortedDeltas = (deltas) => Object.fromEntries(Object.keys(deltas)
+    .sort()
+    .map((t) => {
+    const d = deltas[t] ?? { created: 0, deleted: 0 };
+    return [t, { created: d.created, deleted: d.deleted }];
+}));
+/**
+ * Canonical JSON of a segment's plaintext metadata: keys sorted at every level, only the listed fields.
+ * Its sha256 (the "meta hash") is covered by the segment signature and by the ciphertext's AAD, so the
+ * server cannot change a count, an HLC or a delta without the client noticing. Table names are never
+ * integer-like (they start with a letter), so JSON.stringify keeps the sorted insertion order.
+ */
+export function segmentMetaCanonical(m) {
+    return JSON.stringify({
+        deltas: sortedDeltas(m.deltas),
+        hlcMax: m.hlcMax,
+        hlcMin: m.hlcMin,
+        opCount: m.opCount,
+        schemaVersion: m.schemaVersion,
+    });
+}
+/**
+ * The bytes a device signs (Ed25519) for a journal segment, v2. It binds the ciphertext hash and the
+ * metadata hash to the stream, the replica, the signing device and the replica's position, so a valid
+ * segment cannot be replayed into another stream or position, claimed for another device's replica, or
+ * served with forged metadata.
+ */
+export function segmentSigningMessage(parts) {
+    return lines('cleo-nexus/segment/v2', parts.streamId, parts.replicaId, parts.deviceId, parts.replicaSeq, parts.segmentHash, parts.metaHash);
+}
+/** Canonical JSON of a checkpoint manifest: keys sorted at every level. */
+export function manifestCanonical(m) {
+    return JSON.stringify({
+        schemaVersion: m.schemaVersion,
+        tables: Object.fromEntries(Object.keys(m.tables)
+            .sort()
+            .map((t) => {
+            const e = m.tables[t] ?? { rows: 0, hash: '' };
+            return [t, { hash: e.hash, rows: e.rows }];
+        })),
+    });
+}
+const sortedRecord = (r, f) => Object.fromEntries(Object.keys(r)
+    .sort()
+    .map((k) => [k, f(r[k])]));
+/** Canonical JSON of a checkpoint's replica map: replica ids sorted, then `deviceId`, `lastReplicaSeq`. */
+export function replicasCanonical(r) {
+    return JSON.stringify(sortedRecord(r, (h) => ({ deviceId: h.deviceId, lastReplicaSeq: h.lastReplicaSeq })));
+}
+/** Canonical JSON of revocation pins: `checkpoints` then `replicas`, each with sorted keys. */
+export function revocationPinsCanonical(p) {
+    return JSON.stringify({
+        checkpoints: sortedRecord(p.checkpoints, (n) => n),
+        replicas: sortedRecord(p.replicas, (n) => n),
+    });
+}
+const checkpointFields = (p) => [
+    p.streamId,
+    p.checkpointId,
+    p.parentCheckpointId ?? '-',
+    p.replicaId,
+    p.deviceId,
+    p.coversSeq,
+    p.manifestHash,
+    p.replicasHash,
+    p.blobSha256,
+    p.sizeBytes,
+];
+/**
+ * The bytes the authoring device signs (Ed25519) for a checkpoint, v2. `parentCheckpointId` is `-` for
+ * a genesis checkpoint. A client verifies this before restoring, so an older checkpoint cannot be served
+ * under a newer id, a record's fields cannot be edited, and the replica map that seeds the pull cursor
+ * is the author's.
+ */
+export function checkpointSigningMessage(parts) {
+    return lines('cleo-nexus/checkpoint/v2', ...checkpointFields(parts));
+}
+/**
+ * The bytes another device signs to endorse (re-sign) a checkpoint: the same fields, under their own
+ * domain and the endorser's id, so an endorsement is never mistaken for an authorship.
+ */
+export function checkpointEndorsementMessage(endorserDeviceId, parts) {
+    return lines('cleo-nexus/checkpoint-endorsement/v1', endorserDeviceId, ...checkpointFields(parts));
+}
+/**
+ * The bytes a certified device signs to revoke one signing key of a device and pin its history.
+ */
+export function deviceRevocationMessage(parts) {
+    return lines('cleo-nexus/device-revocation/v1', parts.userId, parts.revokedDeviceId, parts.revokedSigningPublicKeyHex, parts.pinsHash, parts.signerDeviceId);
+}
+/**
+ * The bytes a device certificate MACs: HMAC-SHA256 keyed by HKDF(masterKey, "device-cert"). It binds a
+ * device's public keys to the user and a master key version. Only a master key holder can make one.
+ */
+export function deviceCertificateMessage(parts) {
+    return lines('cleo-nexus/device-cert/v1', parts.userId, parts.deviceId, parts.encryptionPublicKeyHex, parts.signingPublicKeyHex, parts.keyVersion);
+}
+/**
+ * The bytes the granting device signs (Ed25519) for a device key grant. It covers the recipient and
+ * its keys, the key version, the sealed box (by hash) and the recipient's certificate, and names the
+ * signer, so the grant can be neither redirected nor re-attributed.
+ */
+export function deviceGrantMessage(parts) {
+    return lines('cleo-nexus/device-grant/v1', parts.userId, parts.recipientDeviceId, parts.recipientEncryptionPublicKeyHex, parts.recipientSigningPublicKeyHex, parts.keyVersion, parts.sealedMasterKeyHash, parts.certificateHex, parts.signerDeviceId);
+}
+//# sourceMappingURL=signing.js.map

package/dist/cloud/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../../src/cloud/signing.ts"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AAEH,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC;AAC9B,MAAM,KAAK,GAAG,CAAC,GAAG,KAA0B,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAW9E,MAAM,YAAY,GAAG,CAAC,MAAmB,EAAE,EAAE,CAC3C,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;KAChB,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;IACT,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAClD,OAAO,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AACzD,CAAC,CAAC,CACL,CAAC;AAEJ;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAoB;IACvD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9B,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,aAAa,EAAE,CAAC,CAAC,aAAa;KAC/B,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAOrC;IACC,OAAO,KAAK,CACV,uBAAuB,EACvB,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,SAAS,EACf,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,WAAW,EACjB,KAAK,CAAC,QAAQ,CACf,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB,CAAC,CAAW;IAC3C,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,aAAa,EAAE,CAAC,CAAC,aAAa;QAC9B,MAAM,EAAE,MAAM,CAAC,WAAW,CACxB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;aAClB,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;YAC/C,OAAO,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC,CACL;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,YAAY,GAAG,CAAO,CAAoB,EAAE,CAAc,EAAE,EAAE,CAClE,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;KACX,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAM,CAAC,CAAC,CAAC,CACjC,CAAC;AAEJ,2GAA2G;AAC3G,MAAM,UAAU,iBAAiB,CAAC,CAAe;IAC/C,OAAO,IAAI,CAAC,SAAS,CACnB,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CACrF,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,uBAAuB,CAAC,CAAiB;IACvD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAClD,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;KAC7C,CAAC,CAAC;AACL,CAAC;AAiBD,MAAM,gBAAgB,GAAG,CAAC,CAAyB,EAAE,EAAE,CAAC;IACtD,CAAC,CAAC,QAAQ;IACV,CAAC,CAAC,YAAY;IACd,CAAC,CAAC,kBAAkB,IAAI,GAAG;IAC3B,CAAC,CAAC,SAAS;IACX,CAAC,CAAC,QAAQ;IACV,CAAC,CAAC,SAAS;IACX,CAAC,CAAC,YAAY;IACd,CAAC,CAAC,YAAY;IACd,CAAC,CAAC,UAAU;IACZ,CAAC,CAAC,SAAS;CACZ,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAA6B;IACpE,OAAO,KAAK,CAAC,0BAA0B,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAC1C,gBAAwB,EACxB,KAA6B;IAE7B,OAAO,KAAK,CACV,sCAAsC,EACtC,gBAAgB,EAChB,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAQvC;IACC,OAAO,KAAK,CACV,iCAAiC,EACjC,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,eAAe,EACrB,KAAK,CAAC,0BAA0B,EAChC,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,cAAc,CACrB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAQxC;IACC,OAAO,KAAK,CACV,2BAA2B,EAC3B,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,sBAAsB,EAC5B,KAAK,CAAC,mBAAmB,EACzB,KAAK,CAAC,UAAU,CACjB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAWlC;IACC,OAAO,KAAK,CACV,4BAA4B,EAC5B,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,iBAAiB,EACvB,KAAK,CAAC,+BAA+B,EACrC,KAAK,CAAC,4BAA4B,EAClC,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,mBAAmB,EACzB,KAAK,CAAC,cAAc,EACpB,KAAK,CAAC,cAAc,CACrB,CAAC;AACJ,CAAC"}

package/dist/cloud/streams.d.ts

@@ -0,0 +1,6 @@
+import type { StreamId } from '@cleocode/contracts/cloud';
+/** Journal stream for a project's portable·project ops. */
+export declare const projectStream: (projectId: string) => StreamId;
+/** Journal stream for one account's portable·personal ops (home journal). */
+export declare const homeStream: (userId: string) => StreamId;
+//# sourceMappingURL=streams.d.ts.map

package/dist/cloud/streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../../src/cloud/streams.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,2DAA2D;AAC3D,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,KAAG,QAAkC,CAAC;AAErF,6EAA6E;AAC7E,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,KAAG,QAA4B,CAAC"}

package/dist/cloud/streams.js

@@ -0,0 +1,5 @@
+/** Journal stream for a project's portable·project ops. */
+export const projectStream = (projectId) => `project:${projectId}`;
+/** Journal stream for one account's portable·personal ops (home journal). */
+export const homeStream = (userId) => `home:${userId}`;
+//# sourceMappingURL=streams.js.map

package/dist/cloud/streams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.js","sourceRoot":"","sources":["../../src/cloud/streams.ts"],"names":[],"mappings":"AAEA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAiB,EAAY,EAAE,CAAC,WAAW,SAAS,EAAE,CAAC;AAErF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAc,EAAY,EAAE,CAAC,QAAQ,MAAM,EAAE,CAAC"}

package/dist/decide/audit.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Decision audit trail — one JSONL line per decision in
+ * `.cleo/audit/decisions.jsonl`.
+ *
+ * Each line records the site, provider request id, a hash of the questions,
+ * every answer with its probabilities and confidence, the outcome source
+ * (provider / cache / fallback, plus the fallback reason), latency and cost.
+ *
+ * It NEVER records the API key, the base URL's credentials, or the raw state —
+ * only hashes of the request. Writes are synchronous single-line appends (a
+ * few microseconds, so they do not eat into a sub-second decision budget) and
+ * are swallowed on failure: auditing must never break a decision.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import type { DecisionAnswer, DecisionOutcome, DecisionOutcomeSource } from '@cleocode/contracts';
+/** Project-relative path of the decision audit log. */
+export declare const DECISION_AUDIT_FILE = ".cleo/audit/decisions.jsonl";
+/** Why a fallback was used (absent for provider/cache outcomes). */
+export type DecisionFallbackReason = 'unconfigured' | 'invalid_request' | 'budget_exhausted' | 'budget_cooling_down' | 'budget_unavailable' | 'timeout' | 'unauthorized' | 'insufficient_credits' | 'rate_limited' | 'server_error' | 'network' | 'invalid_response' | 'provider_error';
+/** One audited answer: the decided value plus its distribution. */
+export interface DecisionAuditAnswer {
+    /** Question type. */
+    readonly type: DecisionAnswer['type'];
+    /** Decided value. */
+    readonly value: DecisionAnswer['value'];
+    /** Probability of "yes" (noul only). */
+    readonly probability?: number;
+    /** Per-option / per-level probabilities (choice and score). */
+    readonly probabilities?: Readonly<Record<string, number>> | readonly number[];
+    /** Model confidence. */
+    readonly confidence: number;
+}
+/**
+ * Shadow-mode comparison attached to an audit line by a call site that asks
+ * the provider while still acting (or able to act) on its own heuristic.
+ *
+ * It puts the heuristic's answers next to the decision answers of the same
+ * line, so agreement can be measured before a site switches to acting on the
+ * decision.
+ */
+export interface DecisionShadowRecord {
+    /** Site mode: `shadow` acts on the heuristic; `on` acts on the decision when one arrived. */
+    readonly mode: 'shadow' | 'on';
+    /** Which answer the site acted on. */
+    readonly acted: 'heuristic' | 'decision';
+    /** The heuristic's overall verdict, in the site's own vocabulary (e.g. `insert`, `warn`). */
+    readonly heuristicVerdict: string;
+    /** The heuristic's answer to every question, in audit form. */
+    readonly heuristicAnswers: Readonly<Record<string, DecisionAuditAnswer>>;
+    /**
+     * Whether every decided value matches the heuristic's value. `null` when no
+     * provider answer was available (fallback), so there was nothing to compare.
+     */
+    readonly agree: boolean | null;
+    /** Question name → the heuristic's own verdict for it, in the site's vocabulary (e.g. `warn`, `pass`). */
+    readonly heuristicVerdicts?: Readonly<Record<string, string>>;
+    /** Question name → the raw score the heuristic's verdict came from (e.g. Tier-1 similarity). */
+    readonly heuristicScores?: Readonly<Record<string, number>>;
+    /** Question name → the subject it asks about (e.g. a task id). */
+    readonly subjects?: Readonly<Record<string, string>>;
+    /**
+     * Set when the provider answered but the call site refused the answer, so
+     * the heuristic acted. `invalid_choice`: a `choice` value outside the
+     * offered options (T12493).
+     */
+    readonly rejected?: 'invalid_choice';
+}
+/** One line of `.cleo/audit/decisions.jsonl`. */
+export interface DecisionAuditEntry {
+    /** ISO-8601 timestamp. */
+    readonly timestamp: string;
+    /** Call-site identifier passed to `decide()`. */
+    readonly site: string;
+    /** Provider request id, when the outcome came from (or was cached from) a provider. */
+    readonly requestId?: string;
+    /** sha256 of the canonical question set. */
+    readonly questionsHash: string;
+    /** sha256 of the canonical (redacted) state — lets repeats be correlated without storing it. */
+    readonly stateHash: string;
+    /** Question name → audited answer. */
+    readonly answers: Readonly<Record<string, DecisionAuditAnswer>>;
+    /** Where the outcome came from. */
+    readonly source: DecisionOutcomeSource;
+    /** Why the fallback was used (fallback only). */
+    readonly fallbackReason?: DecisionFallbackReason;
+    /** Wall-clock latency of the whole `decide()` call, ms. */
+    readonly latencyMs: number;
+    /** Provider-reported cost in USD, when known. */
+    readonly costUsd?: number;
+    /** Model the request named, when it named one. */
+    readonly model?: string;
+    /** Shadow-mode comparison, when the call site recorded one. */
+    readonly shadow?: DecisionShadowRecord;
+}
+/** Destination for audit entries. Implementations never throw. */
+export interface DecisionAuditSink {
+    /** Record one entry. */
+    write(entry: DecisionAuditEntry): void;
+}
+/**
+ * Project an outcome's answers into audit form.
+ *
+ * @param outcome - The outcome to audit.
+ * @returns Question name → audited answer.
+ */
+export declare function auditAnswers(outcome: DecisionOutcome): Record<string, DecisionAuditAnswer>;
+/** Size at which `decisions.jsonl` is rotated, in bytes. */
+export declare const DEFAULT_DECISION_AUDIT_MAX_BYTES: number;
+/** Rotated generations kept beside the live file (`decisions.jsonl.1` … `.N`). */
+export declare const DEFAULT_DECISION_AUDIT_KEEP = 3;
+/** Rotation bounds for {@link createJsonlDecisionAudit}. */
+export interface DecisionAuditRotation {
+    /** Rotate once the live file reaches this size. Default {@link DEFAULT_DECISION_AUDIT_MAX_BYTES}. */
+    readonly maxBytes?: number;
+    /** Older generations to keep. Default {@link DEFAULT_DECISION_AUDIT_KEEP}. */
+    readonly keep?: number;
+}
+/**
+ * A sink appending to `<projectRoot>/.cleo/audit/decisions.jsonl`, rotated by
+ * size so the audit stays bounded (at most `(keep + 1) × maxBytes`, plus one
+ * line). Rotation is a stat and at most a few renames — cheap enough for the
+ * decision budget.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param rotation - Size cap and generations kept.
+ * @returns A never-throwing {@link DecisionAuditSink}.
+ */
+export declare function createJsonlDecisionAudit(projectRoot: string, rotation?: DecisionAuditRotation): DecisionAuditSink;
+//# sourceMappingURL=audit.d.ts.map

package/dist/decide/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/decide/audit.ts"],"names":[],"mappings":"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"}

package/dist/decide/audit.js

@@ -0,0 +1,98 @@
+/**
+ * Decision audit trail — one JSONL line per decision in
+ * `.cleo/audit/decisions.jsonl`.
+ *
+ * Each line records the site, provider request id, a hash of the questions,
+ * every answer with its probabilities and confidence, the outcome source
+ * (provider / cache / fallback, plus the fallback reason), latency and cost.
+ *
+ * It NEVER records the API key, the base URL's credentials, or the raw state —
+ * only hashes of the request. Writes are synchronous single-line appends (a
+ * few microseconds, so they do not eat into a sub-second decision budget) and
+ * are swallowed on failure: auditing must never break a decision.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import { appendFileSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** Project-relative path of the decision audit log. */
+export const DECISION_AUDIT_FILE = '.cleo/audit/decisions.jsonl';
+/**
+ * Project an outcome's answers into audit form.
+ *
+ * @param outcome - The outcome to audit.
+ * @returns Question name → audited answer.
+ */
+export function auditAnswers(outcome) {
+    const out = {};
+    for (const [name, a] of Object.entries(outcome.answers)) {
+        out[name] =
+            a.type === 'noul'
+                ? { type: a.type, value: a.value, probability: a.probability, confidence: a.confidence }
+                : {
+                    type: a.type,
+                    value: a.value,
+                    probabilities: a.probabilities,
+                    confidence: a.confidence,
+                };
+    }
+    return out;
+}
+/** Size at which `decisions.jsonl` is rotated, in bytes. */
+export const DEFAULT_DECISION_AUDIT_MAX_BYTES = 5 * 1024 * 1024;
+/** Rotated generations kept beside the live file (`decisions.jsonl.1` … `.N`). */
+export const DEFAULT_DECISION_AUDIT_KEEP = 3;
+/** Shift `file` → `file.1` → … → `file.keep`, dropping the oldest. */
+function rotate(file, keep) {
+    rmSync(`${file}.${keep}`, { force: true });
+    for (let i = keep - 1; i >= 1; i--) {
+        try {
+            renameSync(`${file}.${i}`, `${file}.${i + 1}`);
+        }
+        catch {
+            // Generation absent — nothing to shift.
+        }
+    }
+    if (keep >= 1)
+        renameSync(file, `${file}.1`);
+    else
+        rmSync(file, { force: true });
+}
+/**
+ * A sink appending to `<projectRoot>/.cleo/audit/decisions.jsonl`, rotated by
+ * size so the audit stays bounded (at most `(keep + 1) × maxBytes`, plus one
+ * line). Rotation is a stat and at most a few renames — cheap enough for the
+ * decision budget.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param rotation - Size cap and generations kept.
+ * @returns A never-throwing {@link DecisionAuditSink}.
+ */
+export function createJsonlDecisionAudit(projectRoot, rotation = {}) {
+    const dir = join(projectRoot, '.cleo', 'audit');
+    const file = join(dir, 'decisions.jsonl');
+    const maxBytes = Math.max(1, rotation.maxBytes ?? DEFAULT_DECISION_AUDIT_MAX_BYTES);
+    const keep = Math.max(0, Math.floor(rotation.keep ?? DEFAULT_DECISION_AUDIT_KEEP));
+    return {
+        write(entry) {
+            try {
+                mkdirSync(dir, { recursive: true });
+                let size = 0;
+                try {
+                    size = statSync(file).size;
+                }
+                catch {
+                    // No live file yet.
+                }
+                if (size >= maxBytes)
+                    rotate(file, keep);
+                appendFileSync(file, `${JSON.stringify(entry)}\n`, 'utf-8');
+            }
+            catch {
+                // Auditing must never break a decision.
+            }
+        },
+    };
+}
+//# sourceMappingURL=audit.js.map

package/dist/decide/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/decide/audit.ts"],"names":[],"mappings":"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"}