archctx 0.1.4 → 0.1.5

package/assets/catalog.yaml

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "archcontext.practice-catalog-manifest/v1",
   "catalogVersion": "2026.06.0",
-  "productVersion": "0.1.4",
+  "productVersion": "0.1.5",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "entries": [
     {
@@ -389,5 +389,5 @@
     "structurizr.dsl",
     "twelve-factor"
   ],
-  "catalogDigest": "sha256:89829151a844ca84c522924c43d7b174ff613b0b50dbbb2c7174a20d9ac3ab47"
+  "catalogDigest": "sha256:6da748c8c6230d18597951e5ff2de7d483e90caed61435cbd80418a5339c0299"
 }

package/bin/archctx.mjs

@@ -702,7 +702,7 @@ function productVersionManifest() {
     }
   };
 }
-var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.1.4", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", ARCHCONTEXT_NODE_RANGE = ">=24 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-06-25.al0-ledger";
+var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.1.5", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", ARCHCONTEXT_NODE_RANGE = ">=24 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-06-25.al0-ledger";
 // packages/contracts/src/index.ts
 var init_src = __esm(() => {
   init_control_plane_routes();
@@ -9485,7 +9485,7 @@ function migrateLegacyLocalStoreIfNeeded(root = process.cwd(), env = process.env
       integrityCheck.target = "failed";
       integrityCheck.error = error instanceof Error ? error.message : String(error);
       if (!legacyExists) {
-        throw new Error(`ArchContext runtime state target is not a valid SQLite database and no legacy store is available: ${paths.localStorePath}`);
+        return upgradeExistingLocalStoreTarget(paths, integrityCheck);
       }
     }
   }
@@ -9524,6 +9524,28 @@ function migrateLegacyLocalStoreIfNeeded(root = process.cwd(), env = process.env
     releaseLegacyMigrationLock(lock);
   }
 }
+function upgradeExistingLocalStoreTarget(paths, integrityCheck) {
+  const lock = acquireLegacyMigrationLock(paths);
+  try {
+    assertUpgradeableLocalStoreTarget(paths.localStorePath);
+    integrityCheck.target = assertSqliteIntegrity(paths.localStorePath);
+    migrateSqliteDatabaseSync(paths.localStorePath);
+    compactSqliteDatabase(paths.localStorePath);
+    integrityCheck.target = assertCurrentLocalStore(paths.localStorePath);
+    delete integrityCheck.error;
+    const markerPath = writeLegacyMigrationMarker(paths, integrityCheck, []);
+    return legacyMigrationResult(true, undefined, paths, [paths.localStorePath], {
+      status: "target-upgraded",
+      integrityCheck,
+      markerPath,
+      quarantinedFiles: []
+    });
+  } catch (error) {
+    throw new Error(`ArchContext runtime state target is not a valid SQLite database and no legacy store is available: ${paths.localStorePath}; target upgrade failed: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    releaseLegacyMigrationLock(lock);
+  }
+}
 function applyLocalSqliteMigrations(db) {
   for (const pragma of SQLITE_PRAGMAS)
     db.exec(pragma);
@@ -9640,6 +9662,21 @@ function assertCurrentLocalStoreSchema(db, path) {
     throw new Error(`SQLite local store schema incomplete for ${path}: missing migrations ${missingMigrations.join(", ")}`);
   }
 }
+function assertUpgradeableLocalStoreTarget(path) {
+  const db = openSqliteDatabaseSync(path);
+  try {
+    const integrity = sqliteIntegrityCheckOpenDatabase(db, path);
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => String(row.name)));
+    const hasArchContextMarker = ["schema_migrations", "task_states", "repository_sessions", "snapshots"].some((table) => tables.has(table));
+    if (!hasArchContextMarker) {
+      throw new Error(`SQLite target is not an ArchContext local store candidate: ${path}`);
+    }
+    if (integrity !== "ok")
+      throw new Error(`SQLite integrity_check failed for ${path}: ${integrity}`);
+  } finally {
+    db.close();
+  }
+}
 function assertTrustedLegacyLocalStoreSource(paths) {
   const stat = lstatSync(paths.legacyLocalStorePath);
   if (stat.isSymbolicLink()) {
@@ -15961,7 +15998,7 @@ function migrateLegacyLocalStoreIfNeeded2(root = process.cwd(), env = process.en
       integrityCheck.target = "failed";
       integrityCheck.error = error instanceof Error ? error.message : String(error);
       if (!legacyExists) {
-        throw new Error(`ArchContext runtime state target is not a valid SQLite database and no legacy store is available: ${paths.localStorePath}`);
+        return upgradeExistingLocalStoreTarget2(paths, integrityCheck);
       }
     }
   }
@@ -16000,6 +16037,28 @@ function migrateLegacyLocalStoreIfNeeded2(root = process.cwd(), env = process.en
     releaseLegacyMigrationLock2(lock);
   }
 }
+function upgradeExistingLocalStoreTarget2(paths, integrityCheck) {
+  const lock = acquireLegacyMigrationLock2(paths);
+  try {
+    assertUpgradeableLocalStoreTarget2(paths.localStorePath);
+    integrityCheck.target = assertSqliteIntegrity2(paths.localStorePath);
+    migrateSqliteDatabaseSync2(paths.localStorePath);
+    compactSqliteDatabase2(paths.localStorePath);
+    integrityCheck.target = assertCurrentLocalStore2(paths.localStorePath);
+    delete integrityCheck.error;
+    const markerPath = writeLegacyMigrationMarker2(paths, integrityCheck, []);
+    return legacyMigrationResult2(true, undefined, paths, [paths.localStorePath], {
+      status: "target-upgraded",
+      integrityCheck,
+      markerPath,
+      quarantinedFiles: []
+    });
+  } catch (error) {
+    throw new Error(`ArchContext runtime state target is not a valid SQLite database and no legacy store is available: ${paths.localStorePath}; target upgrade failed: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    releaseLegacyMigrationLock2(lock);
+  }
+}
 var RUNTIME_AGENT_JOB_STATUSES = ["queued", "running", "succeeded", "failed", "cancelled", "superseded", "expired"];
 
 class SqliteLocalStore {
@@ -17334,6 +17393,21 @@ function assertCurrentLocalStoreSchema2(db, path) {
     throw new Error(`SQLite local store schema incomplete for ${path}: missing migrations ${missingMigrations.join(", ")}`);
   }
 }
+function assertUpgradeableLocalStoreTarget2(path) {
+  const db = openSqliteDatabaseSync2(path);
+  try {
+    const integrity = sqliteIntegrityCheckOpenDatabase2(db, path);
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => String(row.name)));
+    const hasArchContextMarker = ["schema_migrations", "task_states", "repository_sessions", "snapshots"].some((table) => tables.has(table));
+    if (!hasArchContextMarker) {
+      throw new Error(`SQLite target is not an ArchContext local store candidate: ${path}`);
+    }
+    if (integrity !== "ok")
+      throw new Error(`SQLite integrity_check failed for ${path}: ${integrity}`);
+  } finally {
+    db.close();
+  }
+}
 function assertTrustedLegacyLocalStoreSource2(paths) {
   const stat = lstatSync5(paths.legacyLocalStorePath);
   if (stat.isSymbolicLink()) {
@@ -26460,7 +26534,7 @@ async function runCliUnchecked(command2 = "help", args2 = [], cwd, deps = {}) {
           requestId: "help",
           data: {
             commands: ["init", "sync", "validate", "context", "status", "daemon", "repo", "landscape", "ledger", "book", "recommendations", "explore", "prepare", "practices", "checkpoint", "hook", "hooks", "investigate", "agents", "jobs", "plan", "apply", "review", "complete", "github", "config", "mcp", "install", "uninstall", "doctor", "update", "paths", "privacy-audit", "export", "import", "tunnel"],
-            examples: ["archctx init --name MyApp", "archctx ledger migrate --from-yaml --dry-run", "archctx book recommendations --open --explain", "archctx recommendations accept --id recommendation.<id> --reason 'Accepted after local readback.'", "archctx recommendations metrics", "archctx practices validate --strict", "archctx practices list --json", "archctx practices waivers", "archctx practices waive --practice-id modularity.no-new-cycle --owner team-architecture --reason 'External migration window requires this edge until cutover.' --review-at 2026-07-10T00:00:00.000Z --expires-at 2026-07-24T00:00:00.000Z --evidence-digest sha256:<64-hex> --subject module.a->module.b", "archctx checkpoint --task-session-id task_cli", "archctx investigate --runner-port codex", "archctx agents status --status queued,running", "archctx agents budget", "archctx hook enqueue --event post-edit --path src/app.ts", "archctx jobs list --status queued", "archctx hooks install --host codex", "archctx paths", "archctx update --check", "archctx doctor --check-updates", "archctx github connect", "archctx github status", "archctx daemon start", "archctx explore start --foreground", "archctx export likec4", "archctx import structurizr --content '<json>'", "archctx tunnel"]
+            examples: ["archctx init --name MyApp", "archctx ledger migrate --from-yaml --dry-run", "archctx ledger promote --mode authoritative --preflight --rollback-plan", "archctx book recommendations --open --explain", "archctx recommendations accept --id recommendation.<id> --reason 'Accepted after local readback.'", "archctx recommendations metrics", "archctx practices validate --strict", "archctx practices list --json", "archctx practices waivers", "archctx practices waive --practice-id modularity.no-new-cycle --owner team-architecture --reason 'External migration window requires this edge until cutover.' --review-at 2026-07-10T00:00:00.000Z --expires-at 2026-07-24T00:00:00.000Z --evidence-digest sha256:<64-hex> --subject module.a->module.b", "archctx checkpoint --task-session-id task_cli", "archctx investigate --runner-port codex", "archctx agents status --status queued,running", "archctx agents budget", "archctx hook enqueue --event post-edit --path src/app.ts", "archctx jobs list --status queued", "archctx hooks install --host codex", "archctx paths", "archctx update --check", "archctx doctor --check-updates", "archctx github connect", "archctx github status", "archctx daemon start", "archctx explore start --foreground", "archctx export likec4", "archctx import structurizr --content '<json>'", "archctx tunnel"]
           }
         };
     }
@@ -26479,6 +26553,24 @@ async function runLedgerCommand(args2, cwd, runtime) {
     const daemon = await requiredLedgerRuntime(runtime);
     return daemon.ledgerDrift(cwd);
   }
+  if (subcommand === "promote") {
+    if (args2.includes("--write") || args2.includes("--enable") || args2.includes("--apply")) {
+      return errorEnvelope("ledger.promote", "AC_SCHEMA_INVALID", "ledger promote is preflight-only; it does not write runtime config or enable authority");
+    }
+    const mode = readFlag(args2, "--mode") ?? args2[1];
+    const targetMode = normalizeLedgerPromotionTargetMode(mode);
+    if (!targetMode) {
+      return errorEnvelope("ledger.promote", "AC_SCHEMA_INVALID", "ledger promote requires --mode authoritative");
+    }
+    if (!args2.includes("--preflight")) {
+      return errorEnvelope("ledger.promote", "AC_SCHEMA_INVALID", "ledger promote requires --preflight");
+    }
+    if (!args2.includes("--rollback-plan")) {
+      return errorEnvelope("ledger.promote", "AC_SCHEMA_INVALID", "ledger promote requires --rollback-plan");
+    }
+    const daemon = await requiredLedgerRuntime(runtime);
+    return runLedgerPromotionPreflight(cwd, daemon, targetMode);
+  }
   if (subcommand === "project") {
     if (!args2.includes("--to-git")) {
       return errorEnvelope("ledger.project", "AC_SCHEMA_INVALID", "ledger project currently requires --to-git");
@@ -26547,13 +26639,124 @@ async function runLedgerCommand(args2, cwd, runtime) {
       expectedWorktreeDigest
     });
   }
-  return errorEnvelope("ledger", "AC_SCHEMA_INVALID", "ledger requires status, state, drift --json, migrate --from-yaml, rebuild --from-git, rollback --to-yaml, or project --to-git");
+  return errorEnvelope("ledger", "AC_SCHEMA_INVALID", "ledger requires status, state, drift --json, promote --mode authoritative --preflight --rollback-plan, migrate --from-yaml, rebuild --from-git, rollback --to-yaml, or project --to-git");
 }
 async function requiredLedgerRuntime(runtime) {
   if (!runtime)
     throw new Error("ledger command requires runtime daemon");
   return runtime();
 }
+function normalizeLedgerPromotionTargetMode(value) {
+  if (value === "authoritative" || value === "ledger-authoritative" || value === "ledger")
+    return "ledger-authoritative";
+  return;
+}
+async function runLedgerPromotionPreflight(cwd, daemon, targetMode) {
+  const stateEnvelope = await daemon.ledgerState(cwd);
+  if (!stateEnvelope.ok)
+    return stateEnvelope;
+  const driftEnvelope = await daemon.ledgerDrift(cwd);
+  if (!driftEnvelope.ok)
+    return driftEnvelope;
+  const state = readObject(stateEnvelope.data);
+  const driftData = readObject(driftEnvelope.data);
+  const architectureLedger = readObject(state.architectureLedger);
+  const phaseFlags = readObject(architectureLedger.phaseFlags);
+  const currentPhase = String(phaseFlags.activePhase ?? architectureLedger.rolloutMode ?? "unknown");
+  const worktree = readObject(state.worktree);
+  const ledger3 = readObject(state.ledger);
+  const yaml = readObject(state.yaml);
+  const drift = readObject(driftData.drift ?? state.drift);
+  const reconcile = readObject(driftData.reconcile ?? state.reconcile);
+  const worktreeDigest = typeof worktree.worktreeDigest === "string" ? worktree.worktreeDigest : "<current>";
+  const nextRequiredPhase = nextLedgerPromotionPhase(currentPhase);
+  const preconditions = {
+    currentPhase,
+    targetMode,
+    noModeSkip: currentPhase === "ledger-shadow" || currentPhase === targetMode,
+    driftClean: drift.ok === true,
+    reconcileClean: reconcile.ok === true,
+    unsupportedYamlFilesAbsent: Number(yaml.unsupportedFileCount ?? 0) === 0,
+    ledgerStatePresent: Number(ledger3.entityCount ?? 0) + Number(ledger3.relationCount ?? 0) + Number(ledger3.constraintCount ?? 0) > 0,
+    rollbackPlanPresent: true,
+    hardEnforcementUnchanged: true
+  };
+  const alreadyActive = currentPhase === targetMode;
+  const ready = !alreadyActive && Object.values(preconditions).every((value) => value === true || typeof value === "string");
+  const reasonCodes = [
+    ...alreadyActive ? ["already-ledger-authoritative"] : [],
+    ...preconditions.noModeSkip ? [] : [`mode-sequence-not-ready:${currentPhase}->${nextRequiredPhase ?? "ledger-shadow"}`],
+    ...preconditions.driftClean ? [] : ["ledger-yaml-drift-not-clean"],
+    ...preconditions.reconcileClean ? [] : ["ledger-reconcile-not-clean"],
+    ...preconditions.unsupportedYamlFilesAbsent ? [] : ["unsupported-yaml-files-present"],
+    ...preconditions.ledgerStatePresent ? [] : ["ledger-state-empty"]
+  ];
+  return okEnvelope("ledger.promote", {
+    schemaVersion: "archcontext.runtime-architecture-ledger-promotion-preflight/v1",
+    targetMode,
+    status: alreadyActive ? "already-active" : ready ? "ready" : "blocked",
+    ready,
+    writes: "none",
+    sideEffects: {
+      ledgerModeChanged: false,
+      hardEnforcementChanged: false,
+      sqliteMutated: false,
+      yamlMutated: false
+    },
+    repository: state.repository,
+    worktree: state.worktree,
+    current: {
+      phase: currentPhase,
+      readMode: architectureLedger.readMode,
+      writeMode: architectureLedger.writeMode,
+      readAuthority: architectureLedger.readAuthority,
+      writeAuthority: architectureLedger.writeAuthority,
+      graphDigest: state.graphDigest,
+      ledgerGraphDigest: ledger3.graphDigest,
+      yamlGraphDigest: yaml.graphDigest
+    },
+    preconditions,
+    reasonCodes,
+    nextRequiredPhase,
+    recommendedEnvironment: {
+      ARCHCONTEXT_LEDGER_MODE: targetMode,
+      ARCHCONTEXT_LEDGER_READ_MODE: "ledger",
+      ARCHCONTEXT_LEDGER_WRITE_MODE: "ledger-with-projection"
+    },
+    rollbackPlan: {
+      required: true,
+      targetAuthority: "yaml",
+      dryRunCommand: "archctx ledger rollback --to-yaml --dry-run",
+      command: `archctx ledger rollback --to-yaml --write --expected-worktree-digest ${worktreeDigest}`,
+      commandTemplate: "archctx ledger rollback --to-yaml --write --expected-worktree-digest <current>",
+      environment: {
+        ARCHCONTEXT_LEDGER_MODE: "yaml",
+        ARCHCONTEXT_LEDGER_READ_MODE: "yaml",
+        ARCHCONTEXT_LEDGER_WRITE_MODE: "yaml"
+      }
+    },
+    boundary: {
+      advisoryDefaultPreserved: true,
+      productionGaClaimed: false,
+      hardEnforcementEnabled: false,
+      operatorActionRequired: true
+    }
+  });
+}
+function nextLedgerPromotionPhase(currentPhase) {
+  if (currentPhase === "yaml")
+    return "dual";
+  if (currentPhase === "dual")
+    return "ledger-shadow";
+  if (currentPhase === "ledger-shadow")
+    return "ledger-authoritative";
+  if (currentPhase === "ledger-authoritative")
+    return null;
+  return "yaml";
+}
+function readObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
 async function runBookCommand(args2, cwd, daemon) {
   const subcommand = args2[0] ?? "status";
   const maxItems = readOptionalNonNegativeIntegerFlag(args2, "--max-items", "book");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Local architecture context CLI for agentic coding workflows.",
   "private": false,
   "type": "module",
@@ -16,7 +16,7 @@
     "README.md"
   ],
   "homepage": "https://archcontext.repoharness.com",
-  "license": "UNLICENSED",
+  "license": "Apache-2.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },