@cleocode/contracts 2026.10.8 → 2026.10.9

package/src/project-hooks.ts

@@ -0,0 +1,256 @@
+/** Project-owned checks shared by Git, harness and worktree adapters (T13343). */
+import { z } from 'zod';
+import type { HookJsonValue } from './heavy-command-hook.js';
+
+/** Invocation origin; CI has stricter failure handling than local adapters. */
+export const HookSourceSchema = z.enum(['agent', 'git', 'worktree', 'direct', 'ci']);
+/** Shared invocation origin. */
+export type HookSource = z.infer<typeof HookSourceSchema>;
+/** A checkout-relative path; runtime validation also resolves symlinks. */
+export const ProjectHookPathSchema = z
+  .string()
+  .min(1)
+  .max(4096)
+  .refine(
+    (value) =>
+      !value.startsWith('/') &&
+      !value.includes('\\') &&
+      !value.split('/').includes('..') &&
+      !/^[A-Za-z]:/.test(value),
+    'Expected a project-relative path without traversal',
+  );
+/** One project definition; CLEO IDs are reserved for shipped infrastructure. */
+export const ProjectHookDefinitionSchema = z
+  .object({
+    id: z
+      .string()
+      .regex(/^[a-z][a-z0-9.-]{0,127}$/)
+      .refine((value) => !value.startsWith('cleo.'), 'CLEO IDs are reserved'),
+    owner: z.literal('project'),
+    bindings: z
+      .array(z.object({ source: HookSourceSchema, event: z.string().min(1).max(128) }).strict())
+      .min(1)
+      .max(16),
+    executable: z.string().min(1).max(4096),
+    handler: ProjectHookPathSchema,
+    args: z.array(z.string().max(8192)).max(64).default([]),
+    dependencies: z.array(ProjectHookPathSchema).max(128).default([]),
+    timeoutMs: z.number().int().min(1).max(120000).default(30000),
+    checkerErrorPolicy: z.enum(['warn', 'block']).default('warn'),
+  })
+  .strict();
+/** Validated project checker configuration. Handler is executable's first argument. */
+export type ProjectHookDefinition = z.infer<typeof ProjectHookDefinitionSchema>;
+/** Tracked single source of truth; array order defines execution order. */
+export const ProjectHooksManifestSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    hooks: z.array(ProjectHookDefinitionSchema).max(64),
+  })
+  .strict()
+  .superRefine((manifest, context) => {
+    const ids = new Set<string>();
+    for (const hook of manifest.hooks) {
+      if (ids.has(hook.id))
+        context.addIssue({ code: 'custom', message: `Duplicate hook ID: ${hook.id}` });
+      ids.add(hook.id);
+      const bindings = new Set<string>();
+      for (const binding of hook.bindings) {
+        const key = `${binding.source}:${binding.event}`;
+        if (bindings.has(key))
+          context.addIssue({ code: 'custom', message: `Duplicate binding: ${hook.id}:${key}` });
+        bindings.add(key);
+      }
+    }
+  });
+/** Validated tracked manifest. */
+export type ProjectHooksManifest = z.infer<typeof ProjectHooksManifestSchema>;
+/** Exact ref update supplied by Git pre-push, including zero object IDs. */
+export interface HookRefUpdate {
+  /** Local ref name or deletion marker. */
+  localRef: string;
+  /** Exact local object ID. */
+  localOid: string;
+  /** Remote ref name. */
+  remoteRef: string;
+  /** Previous remote object ID. */
+  remoteOid: string;
+}
+/** Native input normalized by the adapter; no harness environment is required. */
+export interface HookInvocation {
+  /** Protocol version. */
+  schemaVersion: 1;
+  /** Active checkout root, independently resolved through Git. */
+  projectRoot: string;
+  /** Git common directory, for attribution across linked checkouts. */
+  gitCommonDir: string;
+  /** Triggering adapter. */
+  source: HookSource;
+  /** Canonical event name. */
+  event: string;
+  /** Optional remote name and URL/path as Git supplies them. */
+  remote?: { name: string; location: string };
+  /** All pushed ref updates in original order. */
+  refs?: HookRefUpdate[];
+  /** Agent tool input, passed only to the checker and never persisted. */
+  toolInput?: HookJsonValue;
+  /** Optional worktree lifecycle identity. */
+  worktree?: { taskId: string; path: string };
+}
+/** Structured checker verdict written as one JSON object on stdout. */
+export const ProjectHookVerdictSchema = z
+  .object({
+    status: z.enum(['pass', 'block', 'warn', 'skip', 'checker-error']),
+    message: z.string().max(4096).optional(),
+  })
+  .strict();
+/** Project checker's portable stdout contract. */
+export type ProjectHookVerdict = z.infer<typeof ProjectHookVerdictSchema>;
+/** Distinct executor result classes. */
+export type HookOutcomeStatus = ProjectHookVerdict['status'] | 'timeout' | 'infrastructure-error';
+/** Sanitized result: arbitrary child output and inputs are deliberately absent. */
+export interface HookOutcome {
+  /** Project check ID, or CLEO infrastructure attribution. */
+  id: string;
+  /** Observed classification. */
+  status: HookOutcomeStatus;
+  /** Whether this adapter must prevent the operation. */
+  blocks: boolean;
+  /** Safe executor diagnostic code; child messages are not retained. */
+  code: string;
+  /** Project diagnostic for the current caller only; excluded from stored receipts. */
+  message?: string;
+  /** Child exit code; null when no normal exit occurred. */
+  exitCode: number | null;
+  /** Terminating signal, when present. */
+  signal: string | null;
+  /** Elapsed execution time in milliseconds. */
+  durationMs: number;
+}
+/** Dependency-injection port; worktree consumes this without importing core. */
+export interface HookExecutor {
+  /** Execute all matching activated definitions in manifest order. */
+  execute(invocation: HookInvocation): Promise<HookOutcome[]>;
+}
+/** Content hashes approved explicitly on this machine. */
+export const HookActivationSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    projectRoot: z.string(),
+    projectIdentity: z.string(),
+    manifestHash: z.string().regex(/^[a-f0-9]{64}$/),
+    files: z.record(z.string(), z.string().regex(/^[a-f0-9]{64}$/)),
+    executables: z.record(z.string(), z.string()),
+    activatedAt: z.string(),
+  })
+  .strict();
+/** Activation record is local, excluded from Git and never replicated. */
+export type HookActivation = z.infer<typeof HookActivationSchema>;
+/** Local feature state; activation never confers native harness trust. */
+export const ProjectHooksLocalStateSchema = z
+  .object({
+    hooks: z.object({ project: z.object({ enabled: z.boolean() }).strict() }).strict(),
+    activation: HookActivationSchema.optional(),
+  })
+  .strict();
+/** Local activation settings stored independently of tracked project configuration. */
+export type ProjectHooksLocalState = z.infer<typeof ProjectHooksLocalStateSchema>;
+/** Bounded last execution metadata; contains no input or arbitrary output. */
+export interface HookExecutionReceipt {
+  /** Receipt format version. */
+  schemaVersion: 1;
+  /** Activated source digest. */
+  manifestHash: string;
+  /** Invocation origin. */
+  source: HookSource;
+  /** Event without payload. */
+  event: string;
+  /** Completion timestamp. */
+  recordedAt: string;
+  /** Sanitized outcomes. */
+  outcomes: HookOutcome[];
+}
+/** Validator for sanitized execution records, rejecting unexpected payload fields. */
+export const HookExecutionReceiptSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    manifestHash: z.string().regex(/^[a-f0-9]{64}$/),
+    source: HookSourceSchema,
+    event: z.string().max(128),
+    recordedAt: z.string(),
+    outcomes: z
+      .array(
+        z
+          .object({
+            id: z.string().max(128),
+            status: z.enum([
+              'pass',
+              'block',
+              'warn',
+              'skip',
+              'checker-error',
+              'timeout',
+              'infrastructure-error',
+            ]),
+            blocks: z.boolean(),
+            code: z.string().regex(/^HOOK_[A-Z_]+$/),
+            exitCode: z.number().int().nullable(),
+            signal: z.string().max(32).nullable(),
+            durationMs: z.number().nonnegative(),
+          })
+          .strict(),
+      )
+      .max(65),
+  })
+  .strict();
+/** Checkout identity and machine-local receipt paths resolved by Git. */
+export interface ProjectHookContext {
+  /** Active checkout root. */
+  projectRoot: string;
+  /** Common Git directory. */
+  gitCommonDir: string;
+  /** Effective Git hook directory. */
+  hooksDir: string;
+  /** Per-checkout Git-private CLEO state directory. */
+  stateDir: string;
+}
+/** Resolved handler attribution without executing project code. */
+export interface ProjectHookResolution {
+  /** Project-owned definition identity. */
+  id: string;
+  /** Declared policy owner, separate from installer provenance. */
+  owner: 'project';
+  /** Manifest source path. */
+  sourceDefinition: string;
+  /** Whether Git currently tracks the manifest. */
+  sourceTracked: boolean;
+  /** Canonical handler path when it can be resolved safely. */
+  handlerPath?: string;
+  /** Canonical executable path when available. */
+  executablePath?: string;
+  /** Bounded diagnostic codes; contains no environment values. */
+  diagnostics: string[];
+}
+/** Read-only activation and ownership diagnostic. */
+export interface ProjectHookInspection {
+  /** Git-resolved paths. */
+  context: ProjectHookContext;
+  /** Validated source definitions. */
+  manifest: ProjectHooksManifest;
+  /** Definition attribution and resolved executable paths. */
+  resolvedHooks: ProjectHookResolution[];
+  /** Machine-local opt-in flag. */
+  enabled: boolean;
+  /** Activation is absent, fresh or drifted; `unreleased` while this build has not released hooks-v1 (T13557), whatever the receipt says. */
+  activation: 'disabled' | 'missing' | 'active' | 'drifted' | 'unreleased';
+  /** Safe assessment codes. */
+  diagnostics: string[];
+  /** Native harness trust cannot be inferred from files on disk. */
+  nativeTrust: 'unverified';
+  /** Native project trust is independent of CLEO activation. */
+  nativeProjectTrust: 'unverified';
+  /** Exact native hook-definition trust is independent of project trust. */
+  nativeHookTrust: 'unverified';
+  /** Last bounded execution record when valid. */
+  lastExecution?: HookExecutionReceipt;
+}

package/src/release/channel.ts

@@ -10,7 +10,7 @@
  */
 
 /** npm dist-tag channel for a release. */
-export type ReleaseChannel = 'latest' | 'beta' | 'alpha';
+export type ReleaseChannel = 'latest' | 'beta' | 'alpha' | 'canary';
 
 /** Result of validating a version string against a channel's expectations. */
 export interface ChannelValidationResult {

package/src/release/hook-pilot.ts

@@ -0,0 +1,163 @@
+/** Bound, retained evidence required before promoting project hooks to stable (T13350). */
+import { z } from 'zod';
+
+/** Required pilot checks; every named check must pass on the same implementation. */
+export const HOOK_PILOT_CHECKS = [
+  'packedArtifact',
+  'publishedCanary',
+  'readOnlyDev',
+  'readOnlyProd',
+  'liveClaude',
+  'liveCodex',
+  'hostedCi',
+] as const;
+/** A required hook pilot check. */
+export type HookPilotCheck = (typeof HOOK_PILOT_CHECKS)[number];
+/** SHA-256 evidence or implementation digest. */
+export const HookPilotDigestSchema = z.string().regex(/^[a-f0-9]{64}$/);
+/** An independent, numbered canary release; RC/beta does not satisfy this pilot. */
+export const HookPilotCanarySchema = z.string().regex(/^\d{4}\.\d+\.\d+-canary\.\d+$/);
+/** Exact live harness versions, kept separate from source-version normalization. */
+export const HookPilotHarnessVersionsSchema = z
+  .object({
+    claude: z.string().min(1).max(128),
+    codex: z.string().min(1).max(128),
+  })
+  .strict();
+/** Retained proof path remains inside the evidence artifact directory. */
+export const HookPilotProofReferenceSchema = z
+  .object({
+    path: z
+      .string()
+      .min(1)
+      .max(4096)
+      .refine(
+        (value) =>
+          !value.startsWith('/') &&
+          !value.includes('\\') &&
+          !value.split('/').includes('..') &&
+          !/^[A-Za-z]:/.test(value),
+        'Expected a relative proof path without traversal',
+      ),
+    sha256: HookPilotDigestSchema,
+  })
+  .strict();
+/** Common identity attached to every retained proof, never inferred from similar releases. */
+export const HookPilotIdentitySchema = z
+  .object({
+    canaryVersion: HookPilotCanarySchema,
+    sourceDigest: HookPilotDigestSchema,
+    vidaCommit: z.string().regex(/^[a-f0-9]{40}$/),
+    harnessVersions: HookPilotHarnessVersionsSchema,
+  })
+  .strict();
+/** A bounded collection of actual pilot receipts. Missing or partial checks hold promotion. */
+export const HookPilotEvidenceSchema = HookPilotIdentitySchema.extend({
+  schemaVersion: z.literal(1),
+  vidaRepository: z
+    .string()
+    .regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/)
+    .max(256),
+  hostedRunId: z.number().int().positive().safe(),
+  checks: z
+    .object({
+      packedArtifact: HookPilotProofReferenceSchema,
+      publishedCanary: HookPilotProofReferenceSchema,
+      readOnlyDev: HookPilotProofReferenceSchema,
+      readOnlyProd: HookPilotProofReferenceSchema,
+      liveClaude: HookPilotProofReferenceSchema,
+      liveCodex: HookPilotProofReferenceSchema,
+      hostedCi: HookPilotProofReferenceSchema,
+    })
+    .strict(),
+}).strict();
+/** Validated evidence bundle index. */
+export type HookPilotEvidence = z.infer<typeof HookPilotEvidenceSchema>;
+/** Structured, redacted proof produced by a real check and retained with its hash. */
+export const HookPilotProofSchema = HookPilotIdentitySchema.extend({
+  schemaVersion: z.literal(1),
+  check: z.enum(HOOK_PILOT_CHECKS),
+  status: z.literal('pass'),
+  observedAt: z.string().datetime(),
+  checkedCount: z.number().int().min(1).max(100000),
+  exitCode: z.literal(0),
+  mode: z.enum(['packed-artifact', 'published-canary', 'read-only', 'live-harness', 'hosted-ci']),
+  packageVersions: z.record(z.string().max(256), z.string().max(128)).optional(),
+  ordinaryCommands: z.number().int().min(1).max(100000).optional(),
+  disposablePushes: z.number().int().min(1).max(100000).optional(),
+  hostedRunId: z.number().int().positive().safe().optional(),
+  url: z.string().url().max(2048).optional(),
+}).strict();
+/** A validated retained proof. */
+export type HookPilotProof = z.infer<typeof HookPilotProofSchema>;
+/** Minimal authoritative GitHub response required for an actual successful workflow run. */
+export const HookPilotHostedRunSchema = z.object({
+  id: z.number().int().positive(),
+  head_sha: z.string().regex(/^[a-f0-9]{40}$/),
+  status: z.literal('completed'),
+  conclusion: z.literal('success'),
+  path: z.string().max(4096),
+  html_url: z.string().url().max(2048),
+  repository: z.object({ full_name: z.string().max(256) }),
+});
+/** Minimal runner/step evidence; an empty never-started job cannot satisfy hosted CI. */
+export const HookPilotHostedJobsSchema = z.object({
+  jobs: z
+    .array(
+      z.object({
+        name: z.string().max(256),
+        status: z.string().max(32),
+        conclusion: z.string().nullable(),
+        runner_id: z.number().int(),
+        runner_name: z.string().nullable(),
+        labels: z.array(z.string().max(128)).max(32),
+        steps: z
+          .array(
+            z.object({
+              name: z.string().max(512),
+              status: z.string().max(32),
+              conclusion: z.string().nullable(),
+            }),
+          )
+          .max(256),
+      }),
+    )
+    .max(100),
+});
+/** A bounded API JSON reader. Production uses gh; tests inject only transport responses. */
+export type HookPilotApiReader = (endpoint: string) => string;
+/** Inputs that bind validation to the release currently being promoted. */
+export interface HookPilotValidationOptions {
+  /** Repository checkout used for the normalized implementation digest. */
+  root: string;
+  /** Retained evidence index; its directory contains all proof files. */
+  evidencePath: string;
+  /** Stable version receiving promotion; cannot precede the canary base. Source proof must match. */
+  stableVersion: string;
+  /** Trusted release-side pilot repository; evidence cannot redirect authority. */
+  vidaRepository: string;
+  /** Authoritative read transport, injectable for sanitized tests. */
+  readApi?: HookPilotApiReader;
+}
+/** Reusable normalized source digest and exact publish cohort. */
+export interface HookPilotSourceDigest {
+  /** Algorithm format, including inclusion and normalization rules. */
+  schemaVersion: 1;
+  /** SHA-256 of sorted framed mode/path/content records with manifest normalization. */
+  digest: string;
+  /** Number of assessed tracked files. */
+  fileCount: number;
+  /** Package names from release.yml's publish_pkg SSoT. */
+  cohort: string[];
+}
+/** Validation result contains attribution only, never proof payloads or credentials. */
+export interface HookPilotValidationResult {
+  /** Confirmed independent canary. */
+  canaryVersion: string;
+  /** Normalized source digest used by this validation. */
+  sourceDigest: string;
+  /** Exact VidaPeps commit validated by hosted CI. */
+  vidaCommit: string;
+  /** Required checks validated. */
+  checks: HookPilotCheck[];
+}

package/src/release/plan.test.ts

@@ -133,8 +133,8 @@ describe('Release plan constant tuples', () => {
     expect(RELEASE_STATUS).toHaveLength(8);
   });
 
-  it('exports the 4-channel set (latest|beta|alpha|rc)', () => {
-    expect(new Set(RELEASE_CHANNEL)).toEqual(new Set(['latest', 'beta', 'alpha', 'rc']));
+  it('exports the independent canary channel alongside existing channels', () => {
+    expect(new Set(RELEASE_CHANNEL)).toEqual(new Set(['latest', 'beta', 'alpha', 'rc', 'canary']));
   });
 
   it('exports the 3-scheme set including calver-suffix', () => {
@@ -254,10 +254,22 @@ describe('ReleasePlanSchema — status FSM', () => {
 
 describe('ReleasePlanSchema — enum rejection', () => {
   it('rejects unknown channel', () => {
-    const plan = { ...makeValidPlan(), channel: 'canary' };
+    const plan = { ...makeValidPlan(), channel: 'rolling' };
     expect(() => parseReleasePlan(plan)).toThrow();
   });
 
+  it('accepts numbered canaries and rejects channel/version disagreement', () => {
+    const plan = {
+      ...makeValidPlan(),
+      version: 'v2026.10.6-canary.1',
+      resolvedVersion: 'v2026.10.6-canary.1',
+      channel: 'canary',
+    };
+    expect(parseReleasePlan(plan).channel).toBe('canary');
+    expect(() => parseReleasePlan({ ...plan, channel: 'latest' })).toThrow();
+    expect(() => parseReleasePlan({ ...plan, resolvedVersion: 'v2026.10.6-canary' })).toThrow();
+  });
+
   it('rejects unknown scheme', () => {
     const plan = { ...makeValidPlan(), scheme: 'rolling' };
     expect(() => parseReleasePlan(plan)).toThrow();

package/src/release/plan.ts

@@ -52,7 +52,15 @@ export const RELEASE_PLAN_SCHEMA_URL = 'https://cleocode.io/schemas/release-plan
  * Includes `rc` in addition to the legacy `latest|beta|alpha` triple to allow
  * release candidates without conflating with `beta` per SPEC §6.1.
  */
-export const RELEASE_CHANNEL = ['latest', 'beta', 'alpha', 'rc'] as const;
+export const RELEASE_CHANNEL = ['latest', 'beta', 'alpha', 'rc', 'canary'] as const;
+/** Persisted prerelease classification, shared by planning and reconciliation. */
+export const RELEASE_PERSISTED_CHANNEL = {
+  latest: 'latest',
+  beta: 'beta',
+  alpha: 'dev',
+  rc: 'beta',
+  canary: 'beta',
+} as const;
 
 /**
  * Version-scheme variants. `calver-suffix` is the hotfix grammar
@@ -347,61 +355,78 @@ export const ReleasePlanMetaSchema = z
  * - R-305: `platformMatrix[]` non-empty.
  * - R-306: deterministic re-validation inside `open` and `reconcile`.
  */
-export const ReleasePlanSchema = z.object({
-  /** Schema URL for this plan version. */
-  $schema: z.string().optional(),
-  /** Requested version string (e.g. "v2026.6.0"). Includes the leading `v`. */
-  version: NonEmptyString,
-  /** Resolved version string after suffix application (e.g. "v2026.6.0.2"). */
-  resolvedVersion: NonEmptyString,
-  /** True if a `calver-suffix` was applied to disambiguate a same-day hotfix. */
-  suffixApplied: z.boolean(),
-  /** Versioning scheme governing `version` / `resolvedVersion`. */
-  scheme: ReleaseSchemeSchema,
-  /** npm dist-tag channel for this release. */
-  channel: ReleaseChannelSchema,
-  /**
-   * Epic ID this release ships: the `--epic` epic or the `--saga` saga. `null`
-   * for a `--tasks` plan, whose tasks may span several epics; each task's own
-   * epic is on its `epicAncestor` (T13323).
-   */
-  epicId: NonEmptyString.nullable(),
-  /** Release-kind classification. */
-  releaseKind: ReleaseKindSchema,
-  /** ISO-8601 timestamp the plan was written. */
-  createdAt: Iso8601,
-  /** Identifier of the actor that wrote the plan (agent name or operator). */
-  createdBy: NonEmptyString,
-  /**
-   * Version of the previous release on the same channel. MUST be `null` only
-   * for first-ever releases (R-300, enforced at the verb layer).
-   */
-  previousVersion: z.string().nullable(),
-  /** Git tag of the previous release (typically `previousVersion` prefixed). */
-  previousTag: z.string().nullable(),
-  /** ISO-8601 timestamp the previous release was published. */
-  previousShippedAt: Iso8601.nullable(),
-  /** Tasks rolled into this release. */
-  tasks: z.array(ReleasePlanTaskSchema),
-  /** Bucketed changelog. */
-  changelog: ReleasePlanChangelogSchema,
-  /** Per-gate verification status. */
-  gates: z.array(ReleaseGateSchema),
-  /** Platform / publisher matrix. */
-  platformMatrix: z.array(ReleasePlatformMatrixEntrySchema),
-  /** Preflight summary from `cleo release plan`. */
-  preflightSummary: ReleasePreflightSummarySchema,
-  /** URL of the GHA workflow run (populated by `release-prepare.yml`). */
-  workflowRunUrl: z.string().nullable(),
-  /** URL of the bump PR (populated by `cleo release open`). */
-  prUrl: z.string().nullable(),
-  /** Merge commit SHA on `main` (populated by `release-publish.yml`). */
-  mergeCommitSha: z.string().nullable(),
-  /** Current FSM state per R-302. */
-  status: ReleaseStatusSchema,
-  /** Informational / forward-compat metadata. */
-  meta: ReleasePlanMetaSchema.optional(),
-});
+export const ReleasePlanSchema = z
+  .object({
+    /** Schema URL for this plan version. */
+    $schema: z.string().optional(),
+    /** Requested version string (e.g. "v2026.6.0"). Includes the leading `v`. */
+    version: NonEmptyString,
+    /** Resolved version string after suffix application (e.g. "v2026.6.0.2"). */
+    resolvedVersion: NonEmptyString,
+    /** True if a `calver-suffix` was applied to disambiguate a same-day hotfix. */
+    suffixApplied: z.boolean(),
+    /** Versioning scheme governing `version` / `resolvedVersion`. */
+    scheme: ReleaseSchemeSchema,
+    /** npm dist-tag channel for this release. */
+    channel: ReleaseChannelSchema,
+    /**
+     * Epic ID this release ships: the `--epic` epic or the `--saga` saga. `null`
+     * for a `--tasks` plan, whose tasks may span several epics; each task's own
+     * epic is on its `epicAncestor` (T13323).
+     */
+    epicId: NonEmptyString.nullable(),
+    /** Release-kind classification. */
+    releaseKind: ReleaseKindSchema,
+    /** Explicit hooks-v1 stable promotion; ordinary and hotfix releases are exempt. */
+    hooksV1Promotion: z.boolean().optional(),
+    /** ISO-8601 timestamp the plan was written. */
+    createdAt: Iso8601,
+    /** Identifier of the actor that wrote the plan (agent name or operator). */
+    createdBy: NonEmptyString,
+    /**
+     * Version of the previous release on the same channel. MUST be `null` only
+     * for first-ever releases (R-300, enforced at the verb layer).
+     */
+    previousVersion: z.string().nullable(),
+    /** Git tag of the previous release (typically `previousVersion` prefixed). */
+    previousTag: z.string().nullable(),
+    /** ISO-8601 timestamp the previous release was published. */
+    previousShippedAt: Iso8601.nullable(),
+    /** Tasks rolled into this release. */
+    tasks: z.array(ReleasePlanTaskSchema),
+    /** Bucketed changelog. */
+    changelog: ReleasePlanChangelogSchema,
+    /** Per-gate verification status. */
+    gates: z.array(ReleaseGateSchema),
+    /** Platform / publisher matrix. */
+    platformMatrix: z.array(ReleasePlatformMatrixEntrySchema),
+    /** Preflight summary from `cleo release plan`. */
+    preflightSummary: ReleasePreflightSummarySchema,
+    /** URL of the GHA workflow run (populated by `release-prepare.yml`). */
+    workflowRunUrl: z.string().nullable(),
+    /** URL of the bump PR (populated by `cleo release open`). */
+    prUrl: z.string().nullable(),
+    /** Merge commit SHA on `main` (populated by `release-publish.yml`). */
+    mergeCommitSha: z.string().nullable(),
+    /** Current FSM state per R-302. */
+    status: ReleaseStatusSchema,
+    /** Informational / forward-compat metadata. */
+    meta: ReleasePlanMetaSchema.optional(),
+  })
+  .superRefine((plan, context) => {
+    const canaryVersion = /-canary\.\d+$/.test(plan.resolvedVersion);
+    const canarySuffix = /-canary(?:\.|$)/.test(plan.resolvedVersion);
+    if (
+      (plan.channel === 'canary' && !canaryVersion) ||
+      (plan.channel !== 'canary' && canarySuffix)
+    ) {
+      context.addIssue({
+        code: 'custom',
+        path: ['channel'],
+        message: 'Numbered canary versions require the independent canary channel.',
+      });
+    }
+  });
 
 // ─── Inferred TypeScript types ───────────────────────────────────────────────
 

package/src/row-identity.ts

@@ -127,6 +127,13 @@ export interface RowIdentitySpec {
   readonly storedRefUids?: readonly StoredRefUid[];
   /** The key is a user-facing display id that a collision re-mints. */
   readonly displayId?: boolean;
+  /**
+   * A LOCAL key column, other than {@link key}, that never travels (T12915):
+   * each device assigns its own value, references from other tables point at
+   * it, and on the wire they carry the row's uid instead. A received row gets
+   * a fresh local value (the next INTEGER id, or its uid for a TEXT column).
+   */
+  readonly localKey?: string;
   /** Task that declared the table. */
   readonly task: string;
 }

package/src/task.ts

@@ -313,6 +313,11 @@ export type EvidenceAtom =
        * `tool:test-affected`'s `untestedPackages` (T12965 review).
        */
       untestedPackages?: string[];
+      /**
+       * Tracked files matching `evidence.runtimePaths` whose working-tree
+       * edits the tree hash left out (T13554).
+       */
+      runtimeExcluded?: string[];
     }
   | {
       /**
@@ -337,6 +342,8 @@ export type EvidenceAtom =
       headSha?: string;
       /** Tool-cache tree hash at verify time; `cleo complete` refuses the atom once it moves. */
       treeHash?: string;
+      /** Tracked `evidence.runtimePaths` files the tree hash left out (T13554). */
+      runtimeExcluded?: string[];
     }
   | {
       kind: 'tool';