@jstn-sdk/ma 0.1.12 → 0.14.0

package/src/runtime/schema-migrations.js

@@ -0,0 +1,162 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readJson, writeJson } from "../fs-utils.js";
+
+export const runtimeSchemaVersion = "0.1.0";
+
+const SCAN_ROOTS = [".ma/context", ".ma/learning", ".ma/hooks/receipts", ".ma/obsidian", "mcp"];
+const ROOT_FILES = [".ma/setup-receipt.json"];
+
+async function listJsonFiles(root, relative = "") {
+  const directory = path.join(root, relative);
+  let entries;
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const child = path.join(relative, entry.name);
+    if (entry.isDirectory()) files.push(...(await listJsonFiles(root, child)));
+    else if (entry.isFile() && entry.name.endsWith(".json")) files.push(child);
+  }
+  return files;
+}
+
+async function migrationFiles(root) {
+  const nested = (
+    await Promise.all(SCAN_ROOTS.map((relative) => listJsonFiles(root, relative)))
+  ).flat();
+  return [...new Set([...nested, ...ROOT_FILES])].filter(async (relative) => {
+    try {
+      return (await fs.stat(path.join(root, relative))).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+
+// Promise.filter is intentionally avoided: this keeps the scan synchronous in its final form.
+async function existingMigrationFiles(root) {
+  const files = await migrationFiles(root);
+  return (
+    await Promise.all(
+      files.map(async (relative) => {
+        try {
+          return (await fs.stat(path.join(root, relative))).isFile() ? relative : null;
+        } catch {
+          return null;
+        }
+      }),
+    )
+  ).filter(Boolean);
+}
+
+export async function findOutdatedSchemas(root) {
+  const outdated = [];
+  for (const relative of await existingMigrationFiles(root)) {
+    try {
+      const value = await readJson(path.join(root, relative));
+      if (!value || Array.isArray(value) || typeof value !== "object") {
+        outdated.push({ path: relative, schemaVersion: null, error: "invalid_shape" });
+      } else if (value.schemaVersion !== runtimeSchemaVersion) {
+        outdated.push({
+          path: relative,
+          schemaVersion: value.schemaVersion ?? null,
+          expected: runtimeSchemaVersion,
+        });
+      }
+    } catch {
+      outdated.push({ path: relative, schemaVersion: null, error: "invalid_json" });
+    }
+  }
+  return outdated;
+}
+
+export async function migrateSchemas(root, { dryRun = false, rollback = false } = {}) {
+  const files = await existingMigrationFiles(root);
+  if (rollback) return rollbackSchemas(root);
+
+  const plans = [];
+  for (const relative of files) {
+    try {
+      const value = await readJson(path.join(root, relative));
+      if (!value || Array.isArray(value) || typeof value !== "object") {
+        return {
+          status: "failed",
+          migrated: [],
+          errors: [{ path: relative, error: "invalid_shape" }],
+        };
+      }
+      if (value.schemaVersion !== runtimeSchemaVersion) {
+        plans.push({ relative, value, from: value.schemaVersion ?? null });
+      }
+    } catch {
+      return {
+        status: "failed",
+        migrated: [],
+        errors: [{ path: relative, error: "invalid_json" }],
+      };
+    }
+  }
+  if (dryRun)
+    return {
+      status: plans.length ? "outdated" : "current",
+      dryRun: true,
+      migrated: plans.map(({ relative, from }) => ({
+        path: relative,
+        from,
+        to: runtimeSchemaVersion,
+      })),
+      errors: [],
+    };
+  if (plans.length === 0) return { status: "current", migrated: [], errors: [] };
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupRoot = path.join(root, ".ma", "migrations", "backups", stamp);
+  for (const { relative, value } of plans) {
+    const target = path.join(root, relative);
+    const backup = path.join(backupRoot, relative);
+    await fs.mkdir(path.dirname(backup), { recursive: true });
+    await fs.copyFile(target, backup);
+    await writeJson(target, { ...value, schemaVersion: runtimeSchemaVersion });
+  }
+  await writeJson(path.join(root, ".ma", "migrations", "latest.json"), {
+    schemaVersion: runtimeSchemaVersion,
+    createdAt: new Date().toISOString(),
+    backupRoot: path.relative(root, backupRoot),
+    files: plans.map(({ relative }) => relative),
+  });
+  return {
+    status: "migrated",
+    backupRoot: path.relative(root, backupRoot),
+    migrated: plans.map(({ relative, from }) => ({
+      path: relative,
+      from,
+      to: runtimeSchemaVersion,
+    })),
+    errors: [],
+  };
+}
+
+async function rollbackSchemas(root) {
+  let receipt;
+  try {
+    receipt = await readJson(path.join(root, ".ma", "migrations", "latest.json"));
+  } catch {
+    return { status: "current", restored: [], errors: [] };
+  }
+  const restored = [];
+  for (const relative of receipt.files ?? []) {
+    const source = path.join(root, receipt.backupRoot, relative);
+    const target = path.join(root, relative);
+    try {
+      await fs.copyFile(source, target);
+      restored.push(relative);
+    } catch {
+      return { status: "failed", restored, errors: [{ path: relative, error: "backup_missing" }] };
+    }
+  }
+  return { status: "rolled_back", restored, errors: [] };
+}

package/src/runtime/semantic-recording-core.js

@@ -0,0 +1,147 @@
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const semanticRecordingCoreSchemaVersion = "0.1.0";
+
+export function getSemanticRecordingCorePath() {
+  return getRuntimeSubsystemPath("context", "recording-core.json");
+}
+
+export function createDefaultSemanticRecordingCore() {
+  return {
+    schemaVersion: semanticRecordingCoreSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "First-party semantic recording map for MA runtime context, coordination, evidence, memory, and execution artifacts.",
+    layers: [
+      {
+        id: "activity_trace",
+        semantic_role: "automatic_runtime_trace",
+        mechanism: "runtime_hooks",
+        authority: "append_only_hook_layer",
+        paths: [".ma/logs/maestro-events.ndjson", ".ma/hooks/audit.log"],
+        applies_to: ["$maestro", "gated_lanes", "helper_skills", "team_workers"],
+      },
+      {
+        id: "lifecycle_state",
+        semantic_role: "mode_and_run_lifecycle",
+        mechanism: "ma_runtime_state_api",
+        authority: "leader_or_owning_lane",
+        paths: [".ma/state/maestro-state.json", ".ma/state/manager-runs.json"],
+        applies_to: ["$maestro", "owning_lanes", "executor_roles", "verifier_roles"],
+      },
+      {
+        id: "brain_context",
+        semantic_role: "operator_brain_and_project_context",
+        mechanism: "ma_context_memory_api",
+        authority: "provenance_marked_context_only",
+        paths: [".ma/context/project.md", ".ma/context/recording-core.json", ".ma/memory/notes.md"],
+        applies_to: ["all_applicable_agents", "all_applicable_roles"],
+      },
+      {
+        id: "executable_intent",
+        semantic_role: "approved_plan_and_test_shape",
+        mechanism: "lane_owned_artifacts",
+        authority: "owning_lane",
+        paths: [".ma/plans/", ".ma/specs/", ".ma/decisions.json"],
+        applies_to: ["$arch", "$sage", "$flow", "$vet", "$vibe", "$build", "ralph_execution_core"],
+      },
+      {
+        id: "technical_evidence",
+        semantic_role: "build_and_release_evidence",
+        mechanism: "evidence_lane_and_mcp_sources",
+        authority: "$sage_or_owning_review_lane",
+        paths: [".ma/evidence/sources.json", ".ma/evidence/audits.json", "mcp/servers.json"],
+        applies_to: ["$sage", "$vet", "$build", "reviewer_roles"],
+      },
+      {
+        id: "coordination_plane",
+        semantic_role: "task_claims_mailbox_and_workspace_scope",
+        mechanism: "ma_task_workspace_runtime",
+        authority: "leader_dispatch_with_worker_proposals",
+        paths: [".ma/tasks/", ".ma/workspaces/"],
+        applies_to: ["$maestro", "team_workers", "executor_roles", "verifier_roles"],
+      },
+    ],
+    default_core_capabilities: {
+      obsidian_integration_core: {
+        semantic_role: "brain_context",
+        meaning: "Obsidian supplies operator notes, vault graph, and long-lived brain context.",
+        records_as: "vault_context",
+        never_records_as: "build_evidence",
+        authority:
+          "Plugin-side actions may queue requests or expose note-selection metadata; authoritative changes return through MA lanes.",
+        applies_to: ["all_applicable_agents", "all_applicable_roles", "exported_host_payloads"],
+      },
+      context_economy_core: {
+        semantic_role: "context_budget",
+        meaning:
+          "MA-owned terse summaries reduce context load while preserving exact technical terms, warnings, schemas, and evidence.",
+        safety_valves: [
+          "security_warning",
+          "irreversible_action",
+          "user_confusion",
+          "legal_financial_medical_or_high_stakes_guidance",
+          "verification_failure",
+        ],
+        applies_to: [
+          "all_applicable_agents",
+          "all_applicable_roles",
+          "mcp_descriptors",
+          "docs_issues_summaries",
+        ],
+      },
+      ralph_execution_core: {
+        semantic_role: "story_execution",
+        meaning:
+          "Executor-capable agents and roles consume the same approved PRD/progress contract after MA gates pass.",
+        authority: "$maestro_or_owning_lane_dispatch",
+        applies_to: ["executor_roles", "team_workers", "verifier_followups", "reviewer_followups"],
+      },
+    },
+    hard_rules: [
+      "MA runtime artifacts use first-party .ma paths and product language.",
+      "Obsidian-derived claims are vault_context unless another owning lane explicitly promotes them with evidence.",
+      "Context Economy Core cannot remove warnings, schemas, authority fields, verification failures, or known gaps.",
+      "Ralph Execution Core cannot bypass $arch -> $sage -> $flow -> $vet -> $vibe -> $build.",
+      "Helper roles and workers inherit default-core contracts but do not gain independent release-state authority.",
+    ],
+  };
+}
+
+export function validateSemanticRecordingCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("semantic recording core must be an object");
+  }
+  if (value.schemaVersion !== semanticRecordingCoreSchemaVersion) {
+    throw new Error(`Unsupported semantic recording core schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!Array.isArray(value.layers) || value.layers.length === 0) {
+    throw new Error("semantic recording core requires non-empty layers");
+  }
+  if (!value.default_core_capabilities || typeof value.default_core_capabilities !== "object") {
+    throw new Error("semantic recording core requires default_core_capabilities");
+  }
+  if (
+    value.default_core_capabilities.obsidian_integration_core?.records_as !== "vault_context" ||
+    value.default_core_capabilities.obsidian_integration_core?.never_records_as !== "build_evidence"
+  ) {
+    throw new Error("Obsidian Integration Core must record as vault_context, not build_evidence");
+  }
+  if (JSON.stringify(value).includes(".omx")) {
+    throw new Error("semantic recording core must not expose OMX runtime paths");
+  }
+  return value;
+}
+
+export async function seedSemanticRecordingCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getSemanticRecordingCorePath(),
+    `${JSON.stringify(createDefaultSemanticRecordingCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadSemanticRecordingCore() {
+  return validateSemanticRecordingCore(await readJson(getSemanticRecordingCorePath()));
+}

package/src/runtime/signal-hooks.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
 import { getRuntimeSubsystemPath } from "../paths.js";
 
@@ -34,6 +35,21 @@ export async function seedSignalHookArtifacts() {
         schemaVersion: "0.1.0",
         compatibilityNamespace: ["prebuild", "prerelease"],
         runtimeNamespace: runtimeEvents,
+        activeAutonomy: {
+          enabled: true,
+          stopPolicy: "block_passive_permission_handoff_when_auto_continue_applies",
+          defaultResponse:
+            "AUTO-CONTINUE: continue the current safe branch, execute the next reversible step, then verify before reporting.",
+          stallPatterns: [
+            "should i proceed",
+            "would you like me to continue",
+            "if you want, i can",
+            "if you'd like, i can",
+            "tell me if you want me to",
+            "i can continue if you want",
+            "let me know if you want me to continue",
+          ],
+        },
         hooks: [],
       },
       null,
@@ -50,3 +66,15 @@ export async function loadRuntimeHooksConfig() {
 export async function loadRuntimeHooksAuditLog() {
   return fs.readFile(getRuntimeHooksAuditPath(), "utf8");
 }
+
+export async function loadRuntimeHookReceipts() {
+  const root = path.join(getRuntimeHooksRoot(), "receipts");
+  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  return Promise.all(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .sort((left, right) => right.name.localeCompare(left.name))
+      .slice(0, 20)
+      .map((entry) => readJson(path.join(root, entry.name))),
+  );
+}