archctx-contracts 0.1.5

package/src/practices.ts

@@ -0,0 +1,433 @@
+import type { Json } from "./schema";
+
+export const PRACTICE_SCHEMA_VERSION = "archcontext.practice/v1" as const;
+export const PRACTICE_PROFILE_SCHEMA_VERSION = "archcontext.practice-profile/v1" as const;
+export const PRACTICE_SOURCE_SCHEMA_VERSION = "archcontext.practice-source/v1" as const;
+export const PRACTICE_CATALOG_MANIFEST_SCHEMA_VERSION = "archcontext.practice-catalog-manifest/v1" as const;
+export const PRACTICE_ENFORCEMENT_POLICY_SCHEMA_VERSION = "archcontext.practice-enforcement-policy/v1" as const;
+export const PRACTICE_WAIVER_SCHEMA_VERSION = "archcontext.practice-waiver/v1" as const;
+export const PRACTICE_CHECK_RESULT_SCHEMA_VERSION = "archcontext.practice-check-result/v1" as const;
+
+export type PracticeStatus = "active" | "deprecated" | "disabled";
+export type PracticeOverlayMode = "add" | "replace" | "disable";
+export type PracticeEvidenceStrength = "heuristic" | "declared" | "observed" | "verified";
+export type PracticeEvidenceKind =
+  | "task-text"
+  | "path"
+  | "package-manifest"
+  | "architecture-model"
+  | "symbol"
+  | "import-edge"
+  | "call-edge"
+  | "data-edge"
+  | "diff"
+  | "test"
+  | "runtime-check"
+  | "human-attestation";
+export type PracticeEnforcementLevel = "advisory" | "checkpoint" | "complete";
+export type PracticeSourceTrust = "repo-authored" | "curated-static" | "external-dynamic";
+export type PracticeSourceLicenseLevel = "A" | "B" | "C" | "D" | "E";
+export type PracticeMatchConfidence = "low" | "medium" | "high";
+export type PracticeMatchReason = "retrieval" | "scope" | "signal" | "predicate" | "repo-policy";
+export type PracticeCheckpointEvent = "manual" | "post-edit" | "post-write" | "pre-complete";
+export type PracticeCheckpointReasonCode =
+  | "fresh"
+  | "stale-head"
+  | "stale-worktree"
+  | "stale-catalog"
+  | "no-baseline"
+  | "no-op";
+export type PracticeCheckStatus = "pass" | "fail" | "waived" | "not_applicable";
+export type PracticeEnforcementPolicyMode = "advisory" | "active" | "fail-open" | "fail-closed";
+export type PracticeEnforcementEvaluationMode = "advisory" | "fail-open" | "fail-closed";
+export type PracticeCheckReasonCode =
+  | "policy-disabled"
+  | "not-opted-in"
+  | "not-registered"
+  | "fixture-gate-missing"
+  | "heuristic-only"
+  | "no-baseline"
+  | "no-violation"
+  | "violation"
+  | "waived"
+  | "invalid-waiver";
+
+export interface PracticeScopeV1 {
+  repositoryKinds: string[];
+  languages: string[];
+  frameworks: string[];
+  pathGlobs: string[];
+  nodeKinds: string[];
+  negativePathGlobs?: string[];
+  negativeNodeKinds?: string[];
+}
+
+export interface PracticeTriggersV1 {
+  candidateTerms: string[];
+  pressureSignals: string[];
+  structuralPredicates: string[];
+}
+
+export interface PracticeEvidencePolicyV1 {
+  minimumStrengthForRecommendation: PracticeEvidenceStrength;
+  minimumStrengthForCheckpoint: PracticeEvidenceStrength;
+  minimumStrengthForEnforcement: PracticeEvidenceStrength;
+  requiredKindsForEnforcement: PracticeEvidenceKind[];
+  maxEnforcementWhenOnlyHeuristic: "advisory";
+}
+
+export interface PracticeGuidanceV1 {
+  questions: string[];
+  preferred: string[];
+  avoid: string[];
+}
+
+export interface PracticeCheckV1 {
+  checkId: string;
+  mode: "deterministic";
+  parameters: Record<string, Json>;
+}
+
+export interface PracticeCheckDefinitionV1 extends PracticeCheckV1 {
+  schemaVersion: "archcontext.practice-check-definition/v1";
+  practiceId: string;
+}
+
+export interface PracticeEnforcementV1 {
+  default: PracticeEnforcementLevel;
+  promotableTo: PracticeEnforcementLevel;
+  repoOptInRequired: boolean;
+  fixtureGate?: PracticeEnforcementFixtureGateV1;
+}
+
+export interface PracticeEnforcementFixtureRefV1 {
+  id: string;
+  path: string;
+  description: string;
+  digest?: string;
+}
+
+export interface PracticeEnforcementFixtureGateV1 {
+  positive: PracticeEnforcementFixtureRefV1[];
+  nearNegative: PracticeEnforcementFixtureRefV1[];
+  mixedChange: PracticeEnforcementFixtureRefV1[];
+  baseline: PracticeEnforcementFixtureRefV1[];
+}
+
+export interface PracticeSourceRefV1 {
+  sourceId: string;
+  sourceRevision?: string;
+  licenseSpdx?: string;
+}
+
+export interface PracticeProvenanceV1 {
+  sourceKind: "archcontext-native" | "curated-open-source" | "curated-reference";
+  sourceRefs: PracticeSourceRefV1[];
+  curator: string;
+  reviewedAt: string;
+}
+
+export interface PracticeLifecycleV1 {
+  introducedAt: string;
+  reviewAfter: string;
+  supersedes: string[];
+  disabledWithReason?: string;
+}
+
+export interface PracticeOverlayV1 {
+  mode: PracticeOverlayMode;
+  extends?: string;
+  expiresAt?: string;
+}
+
+export interface PracticeAssetV1 {
+  schemaVersion: typeof PRACTICE_SCHEMA_VERSION;
+  id: string;
+  revision: number;
+  status: PracticeStatus;
+  title: string;
+  summary: string;
+  category: string;
+  tags: string[];
+  appliesTo: PracticeScopeV1;
+  triggers: PracticeTriggersV1;
+  evidencePolicy: PracticeEvidencePolicyV1;
+  guidance: PracticeGuidanceV1;
+  checks: PracticeCheckV1[];
+  enforcement: PracticeEnforcementV1;
+  provenance: PracticeProvenanceV1;
+  lifecycle: PracticeLifecycleV1;
+  overlay?: PracticeOverlayV1;
+}
+
+export interface PracticeProfileV1 {
+  schemaVersion: typeof PRACTICE_PROFILE_SCHEMA_VERSION;
+  id: string;
+  revision: number;
+  status: "active" | "deprecated";
+  title: string;
+  repositoryKinds: string[];
+  languages: string[];
+  frameworks: string[];
+  includePracticeIds: string[];
+  excludePracticeIds: string[];
+  provenance: PracticeProvenanceV1;
+}
+
+export interface PracticePolicyScopeV1 {
+  pathGlobs?: string[];
+  subjects?: string[];
+}
+
+export interface PracticePolicyTestEvidenceV1 {
+  commands?: string[];
+  subjects?: string[];
+}
+
+export interface PracticePolicyRuleV1 {
+  practiceId: string;
+  enforcement: PracticeEnforcementLevel;
+  checkIds?: string[];
+  scope?: PracticePolicyScopeV1;
+  testEvidence?: PracticePolicyTestEvidenceV1;
+}
+
+export interface PracticeRecommendationSchedulerPolicyV1 {
+  enabled?: boolean;
+  policyMode?: "advisory" | "checkpoint" | "complete";
+  frequency?: {
+    minIntervalMs?: number;
+    cooldownMs?: number;
+  };
+  budgets?: {
+    maxRecommendationsPerRun?: number;
+    maxL3InvestigationsPerRun?: number;
+    maxRunsPerTask?: number;
+    maxRunsPerRepositoryPerDay?: number;
+    maxRunsPerDay?: number;
+  };
+}
+
+export interface PracticeEnforcementPolicyV1 {
+  schemaVersion: typeof PRACTICE_ENFORCEMENT_POLICY_SCHEMA_VERSION;
+  mode: PracticeEnforcementPolicyMode;
+  rules: PracticePolicyRuleV1[];
+  recommendations?: PracticeRecommendationSchedulerPolicyV1;
+}
+
+export interface PracticeWaiverV1 {
+  schemaVersion: typeof PRACTICE_WAIVER_SCHEMA_VERSION;
+  practiceId: string;
+  checkId?: string;
+  scope: PracticePolicyScopeV1;
+  owner: string;
+  reason: string;
+  createdAt: string;
+  reviewAt: string;
+  expiresAt: string;
+  evidenceDigest: string;
+}
+
+export interface PracticeSourceRecordV1 {
+  schemaVersion: typeof PRACTICE_SOURCE_SCHEMA_VERSION;
+  id: string;
+  name: string;
+  sourceType: "archcontext" | "git" | "website" | "standard" | "reference";
+  uri: string;
+  revision: string;
+  licenseSpdx: string;
+  licenseLevel: PracticeSourceLicenseLevel;
+  usagePolicy: "builtin-with-attribution" | "reference-only" | "repo-authored";
+  retrievedAt: string;
+  contentDigest: string;
+  attribution: string;
+  review: {
+    status: "approved" | "reference-only" | "blocked";
+    reviewer: string;
+    reviewedAt: string;
+  };
+}
+
+export interface PracticeCatalogManifestEntryV1 {
+  id: string;
+  revision: number;
+  digest: string;
+  sourceIds: string[];
+}
+
+export interface PracticeCatalogManifestV1 {
+  schemaVersion: typeof PRACTICE_CATALOG_MANIFEST_SCHEMA_VERSION;
+  catalogVersion: string;
+  productVersion: string;
+  generatedAt: string;
+  entries: PracticeCatalogManifestEntryV1[];
+  sourceIds: string[];
+  catalogDigest: string;
+}
+
+export interface EffectivePracticeAssetV1 {
+  asset: PracticeAssetV1;
+  assetDigest: string;
+  sourceTrust: PracticeSourceTrust;
+  originPath: string;
+  overrideChain: string[];
+}
+
+export interface PracticeEvidenceV1 {
+  kind: PracticeEvidenceKind;
+  strength: PracticeEvidenceStrength;
+  subject: string;
+  digest?: string;
+  observedAt?: string;
+}
+
+export interface PracticeMatchV1 {
+  schemaVersion: "archcontext.practice-match/v1";
+  practiceId: string;
+  assetRevision: number;
+  assetDigest: string;
+  title: string;
+  category: string;
+  score: number;
+  confidence: PracticeMatchConfidence;
+  enforcement: PracticeEnforcementLevel;
+  matchedBy: PracticeMatchReason[];
+  evidence: PracticeEvidenceV1[];
+  explanation: string[];
+  sourceTrust: PracticeSourceTrust;
+  suppressedReason?: string;
+}
+
+export interface PracticeCheckRemediationV1 {
+  action: string;
+  paths: string[];
+}
+
+export interface PracticeWaiverApplicationV1 {
+  waiverDigest: string;
+  practiceId: string;
+  checkId?: string;
+  owner: string;
+  reviewAt: string;
+  expiresAt: string;
+}
+
+export interface PracticeCheckResultV1 {
+  schemaVersion: typeof PRACTICE_CHECK_RESULT_SCHEMA_VERSION;
+  practiceId: string;
+  checkId: string;
+  assetDigest: string;
+  enforcement: PracticeEnforcementLevel;
+  status: PracticeCheckStatus;
+  reasonCode: PracticeCheckReasonCode;
+  deterministic: true;
+  subjects: string[];
+  subjectDigests: string[];
+  message: string;
+  remediation: PracticeCheckRemediationV1;
+  waiver?: PracticeWaiverApplicationV1;
+}
+
+export interface PracticeEnforcementEvaluationV1 {
+  schemaVersion: "archcontext.practice-enforcement-evaluation/v1";
+  catalogDigest: string;
+  policyDigest: string;
+  policyMode: PracticeEnforcementEvaluationMode;
+  blocking: boolean;
+  checkResultDigest: string;
+  results: PracticeCheckResultV1[];
+  violations: PracticeCheckResultV1[];
+  nonBlockingViolations: PracticeCheckResultV1[];
+  waiversApplied: PracticeWaiverApplicationV1[];
+  actionsRequired: string[];
+}
+
+export interface PracticeGuidanceResultV1 {
+  schemaVersion: "archcontext.practice-guidance/v1";
+  catalogDigest: string;
+  overlayDigest: string;
+  matches: PracticeMatchV1[];
+  constraints: string[];
+  decisions: string[];
+  realConstraints: string[];
+  unknowns: string[];
+  requiredCheckpoints: string[];
+  resources: { type: "practice"; uri: string; digest: string }[];
+}
+
+export interface CheckpointInputV2 {
+  schemaVersion: "archcontext.checkpoint-input/v2";
+  taskSessionId: string;
+  task?: string;
+  headSha?: string;
+  expectedWorktreeDigest?: string;
+  event: PracticeCheckpointEvent;
+  changedPaths: string[];
+  toolCallId?: string;
+}
+
+export interface PracticeCheckpointSnapshotV1 {
+  schemaVersion: "archcontext.practice-checkpoint-snapshot/v1";
+  task: string;
+  headSha: string;
+  worktreeDigest: string;
+  contextDigest: string;
+  practiceGuidanceDigest: string;
+  catalogDigest: string;
+  matches: PracticeMatchV1[];
+}
+
+export interface PracticeDeltaV1 {
+  schemaVersion: "archcontext.practice-delta/v1";
+  added: PracticeMatchV1[];
+  removed: PracticeMatchV1[];
+  upgraded: PracticeMatchV1[];
+  downgraded: PracticeMatchV1[];
+  unchanged: PracticeMatchV1[];
+  requiresProof: PracticeMatchV1[];
+}
+
+export interface PracticeCheckpointResultV1 {
+  schemaVersion: "archcontext.practice-checkpoint/v1";
+  taskSessionId: string;
+  event: PracticeCheckpointEvent;
+  headSha: string;
+  expectedHeadSha?: string;
+  worktreeDigest: string;
+  expectedWorktreeDigest?: string;
+  fresh: boolean;
+  reasonCode: PracticeCheckpointReasonCode;
+  staleReasons: PracticeCheckpointReasonCode[];
+  changedPaths: string[];
+  toolCallId?: string;
+  catalogDigest: string;
+  previousCatalogDigest?: string;
+  contextDigest: string;
+  previousContextDigest?: string;
+  practiceGuidanceDigest: string;
+  previousPracticeGuidanceDigest?: string;
+  delta: PracticeDeltaV1;
+  noOpDigest: string;
+  resultDigest: string;
+  hook: {
+    egress: "none";
+    failOpen: true;
+    pathCount: number;
+    network: "forbidden";
+    pathSummary?: {
+      schemaVersion: "archcontext.checkpoint-path-summary/v1";
+      total: number;
+      source: number;
+      generated: number;
+      ignored: number;
+      binary: number;
+      deleted: number;
+      renameHints: number;
+    };
+    coalesced?: boolean;
+    skippedAnalysis?: boolean;
+    coalescedEventCount?: number;
+    coalesceKey?: string;
+  };
+  nextSnapshot: PracticeCheckpointSnapshotV1;
+}

package/src/product-version.ts

@@ -0,0 +1,108 @@
+export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.1.5";
+export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10";
+export const ARCHCONTEXT_NODE_RANGE = ">=24 <26";
+export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1";
+export const ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-06-25.al0-ledger";
+
+export interface ProductVersionManifest {
+  schemaVersion: "archcontext.product-version-manifest/v1";
+  product: {
+    name: typeof ARCHCONTEXT_PRODUCT_NAME;
+    version: typeof ARCHCONTEXT_PRODUCT_VERSION;
+    distribution: "one-package";
+  };
+  packageManager: typeof ARCHCONTEXT_PACKAGE_MANAGER;
+  engines: {
+    node: typeof ARCHCONTEXT_NODE_RANGE;
+  };
+  surfaces: {
+    cli: ProductSurfaceVersion;
+    daemon: ProductSurfaceVersion & {
+      rpcSchemaVersion: typeof LOCAL_RUNTIME_RPC_SCHEMA_VERSION;
+    };
+    mcp: ProductSurfaceVersion & {
+      transport: "stdio";
+    };
+  };
+  schemas: {
+    schemaSetVersion: typeof ARCHCONTEXT_SCHEMA_SET_VERSION;
+    contractsPackageVersion: typeof ARCHCONTEXT_PRODUCT_VERSION;
+    reviewChallenge: "archcontext.review-challenge/v2";
+    attestation: "archcontext.attestation/v2";
+    deviceIdentity: "archcontext.device-identity/v1";
+    runnerIdentity: "archcontext.runner-identity/v1";
+  };
+  runtime: {
+    localRpc: {
+      schemaVersion: typeof LOCAL_RUNTIME_RPC_SCHEMA_VERSION;
+      protocol: "http-loopback";
+    };
+    sqliteMigrations: string;
+    codeGraph: {
+      packageName: "@colbymchenry/codegraph";
+      requiredVersion: "1.0.1";
+      adapter: "codegraph-cli";
+    };
+  };
+}
+
+interface ProductSurfaceVersion {
+  packageName: string;
+  version: typeof ARCHCONTEXT_PRODUCT_VERSION;
+  entrypoint: string;
+}
+
+export function productVersionManifest(): ProductVersionManifest {
+  return {
+    schemaVersion: "archcontext.product-version-manifest/v1",
+    product: {
+      name: ARCHCONTEXT_PRODUCT_NAME,
+      version: ARCHCONTEXT_PRODUCT_VERSION,
+      distribution: "one-package"
+    },
+    packageManager: ARCHCONTEXT_PACKAGE_MANAGER,
+    engines: {
+      node: ARCHCONTEXT_NODE_RANGE
+    },
+    surfaces: {
+      cli: {
+        packageName: "@archcontext/surfaces",
+        version: ARCHCONTEXT_PRODUCT_VERSION,
+        entrypoint: "archctx"
+      },
+      daemon: {
+        packageName: "@archcontext/local-runtime",
+        version: ARCHCONTEXT_PRODUCT_VERSION,
+        entrypoint: "archctx daemon start",
+        rpcSchemaVersion: LOCAL_RUNTIME_RPC_SCHEMA_VERSION
+      },
+      mcp: {
+        packageName: "@archcontext/surfaces",
+        version: ARCHCONTEXT_PRODUCT_VERSION,
+        entrypoint: "archctx mcp",
+        transport: "stdio"
+      }
+    },
+    schemas: {
+      schemaSetVersion: ARCHCONTEXT_SCHEMA_SET_VERSION,
+      contractsPackageVersion: ARCHCONTEXT_PRODUCT_VERSION,
+      reviewChallenge: "archcontext.review-challenge/v2",
+      attestation: "archcontext.attestation/v2",
+      deviceIdentity: "archcontext.device-identity/v1",
+      runnerIdentity: "archcontext.runner-identity/v1"
+    },
+    runtime: {
+      localRpc: {
+        schemaVersion: LOCAL_RUNTIME_RPC_SCHEMA_VERSION,
+        protocol: "http-loopback"
+      },
+      sqliteMigrations: "0001_runtime_state..0004_changeset_journal",
+      codeGraph: {
+        packageName: "@colbymchenry/codegraph",
+        requiredVersion: "1.0.1",
+        adapter: "codegraph-cli"
+      }
+    }
+  };
+}

package/src/schema.ts

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+
+export type Json =
+  | null
+  | boolean
+  | number
+  | string
+  | Json[]
+  | { [key: string]: Json };
+
+export type Severity = "notice" | "warning" | "error" | "critical";
+
+export type ArchContextErrorCode =
+  | "AC_REPO_NOT_FOUND"
+  | "AC_RUNTIME_UNAVAILABLE"
+  | "AC_RUNTIME_VERSION_UNSUPPORTED"
+  | "AC_CODEGRAPH_UNAVAILABLE"
+  | "AC_INDEX_STALE"
+  | "AC_CONTEXT_STALE"
+  | "AC_SCHEMA_INVALID"
+  | "AC_POLICY_VIOLATION"
+  | "AC_PATH_DENIED"
+  | "AC_PRECONDITION_FAILED"
+  | "AC_CAPABILITY_UNSUPPORTED"
+  | "AC_INTERVENTION_REQUIRED"
+  | "AC_PROOF_REQUIRED"
+  | "AC_COMPAT_CONTRACT_REQUIRED"
+  | "AC_USER_CONFIRMATION_REQUIRED"
+  | "AC_ENTITLEMENT_REQUIRED"
+  | "AC_ATTESTATION_REJECTED"
+  | "AC_TUNNEL_SCOPE_DENIED";
+
+export interface ArchContextError {
+  code: ArchContextErrorCode;
+  message: string;
+  severity: Severity;
+  retryable: boolean;
+  action: string;
+}
+
+export interface JsonEnvelope<T extends Json = Json> {
+  schemaVersion: "archcontext.envelope/v1";
+  ok: boolean;
+  requestId: string;
+  data?: T;
+  error?: ArchContextError;
+}
+
+export const ERROR_CATALOG: Record<ArchContextErrorCode, Omit<ArchContextError, "message">> = {
+  AC_REPO_NOT_FOUND: { code: "AC_REPO_NOT_FOUND", severity: "error", retryable: false, action: "open-correct-repository" },
+  AC_RUNTIME_UNAVAILABLE: { code: "AC_RUNTIME_UNAVAILABLE", severity: "error", retryable: true, action: "start-or-reconnect-runtime" },
+  AC_RUNTIME_VERSION_UNSUPPORTED: { code: "AC_RUNTIME_VERSION_UNSUPPORTED", severity: "error", retryable: true, action: "upgrade-archctx-runtime" },
+  AC_CODEGRAPH_UNAVAILABLE: { code: "AC_CODEGRAPH_UNAVAILABLE", severity: "error", retryable: true, action: "run-diagnostics" },
+  AC_INDEX_STALE: { code: "AC_INDEX_STALE", severity: "warning", retryable: true, action: "sync-codefacts" },
+  AC_CONTEXT_STALE: { code: "AC_CONTEXT_STALE", severity: "warning", retryable: true, action: "prepare-task-again" },
+  AC_SCHEMA_INVALID: { code: "AC_SCHEMA_INVALID", severity: "error", retryable: false, action: "repair-model" },
+  AC_POLICY_VIOLATION: { code: "AC_POLICY_VIOLATION", severity: "error", retryable: false, action: "revise-plan" },
+  AC_PATH_DENIED: { code: "AC_PATH_DENIED", severity: "critical", retryable: false, action: "do-not-bypass" },
+  AC_PRECONDITION_FAILED: { code: "AC_PRECONDITION_FAILED", severity: "warning", retryable: true, action: "rebuild-plan" },
+  AC_CAPABILITY_UNSUPPORTED: { code: "AC_CAPABILITY_UNSUPPORTED", severity: "error", retryable: false, action: "stay-within-single-repository" },
+  AC_INTERVENTION_REQUIRED: { code: "AC_INTERVENTION_REQUIRED", severity: "error", retryable: false, action: "enter-intervention-sop" },
+  AC_PROOF_REQUIRED: { code: "AC_PROOF_REQUIRED", severity: "warning", retryable: false, action: "execute-proof-point" },
+  AC_COMPAT_CONTRACT_REQUIRED: { code: "AC_COMPAT_CONTRACT_REQUIRED", severity: "error", retryable: false, action: "delete-or-contract" },
+  AC_USER_CONFIRMATION_REQUIRED: { code: "AC_USER_CONFIRMATION_REQUIRED", severity: "warning", retryable: true, action: "show-human-decision" },
+  AC_ENTITLEMENT_REQUIRED: { code: "AC_ENTITLEMENT_REQUIRED", severity: "error", retryable: false, action: "login-or-subscribe" },
+  AC_ATTESTATION_REJECTED: { code: "AC_ATTESTATION_REJECTED", severity: "error", retryable: false, action: "review-again" },
+  AC_TUNNEL_SCOPE_DENIED: { code: "AC_TUNNEL_SCOPE_DENIED", severity: "error", retryable: false, action: "reduce-scope" }
+};
+
+export function okEnvelope<T extends Json>(requestId: string, data: T): JsonEnvelope<T> {
+  return { schemaVersion: "archcontext.envelope/v1", ok: true, requestId, data };
+}
+
+export function errorEnvelope(requestId: string, code: ArchContextErrorCode, message: string): JsonEnvelope {
+  return {
+    schemaVersion: "archcontext.envelope/v1",
+    ok: false,
+    requestId,
+    error: { ...ERROR_CATALOG[code], message }
+  };
+}
+
+export function canonicalize(value: Json): string {
+  return JSON.stringify(sortJson(value));
+}
+
+export function digestJson(value: Json): string {
+  return `sha256:${createHash("sha256").update(canonicalize(value), "utf8").digest("hex")}`;
+}
+
+export function stableId(...parts: string[]): string {
+  return parts
+    .map((part) =>
+      part
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+    )
+    .filter(Boolean)
+    .join(".");
+}
+
+export function isRepoRelativePosixPath(path: string): boolean {
+  return path.length > 0 && !path.startsWith("/") && !path.includes("\\") && !path.split("/").includes("..");
+}
+
+export function stableYaml(value: Json, indent = 0): string {
+  const pad = " ".repeat(indent);
+  if (value === null) return "null\n";
+  if (typeof value !== "object") return `${formatScalar(value)}\n`;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]\n";
+    return value
+      .map((item) => {
+        if (item !== null && typeof item === "object") {
+          return `${pad}- ${stableYaml(item, indent + 2).trimStart()}`;
+        }
+        return `${pad}- ${formatScalar(item)}\n`;
+      })
+      .join("");
+  }
+  const keys = Object.keys(value).sort();
+  if (keys.length === 0) return "{}\n";
+  return keys
+    .map((key) => {
+      const entry = value[key];
+      if (entry !== null && typeof entry === "object") {
+        return `${pad}${key}:\n${stableYaml(entry, indent + 2)}`;
+      }
+      return `${pad}${key}: ${formatScalar(entry)}\n`;
+    })
+    .join("");
+}
+
+function sortJson(value: Json): Json {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(sortJson);
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
+}
+
+function formatScalar(value: Json): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  return JSON.stringify(value);
+}