@jstn-sdk/ma 0.1.11 → 0.1.13

package/src/runtime/build-readiness.js

@@ -0,0 +1,62 @@
+import {
+  evaluateBuildGate,
+  formatBuildBlockers,
+  formatNextAllowedTriggers,
+} from "../build-gate.js";
+
+export function evaluateRuntimeBuildReadiness(releaseState, runtimeSummary, options = {}) {
+  const enforceIssueGates = options.enforceIssueGates === true;
+  const releaseEvaluation = evaluateBuildGate(releaseState);
+  const missingArtifacts = runtimeSummary.missingArtifacts.filter(
+    (artifact) => enforceIssueGates || artifact !== "release.issueGates",
+  );
+  const controlPlaneBlockers = [
+    ...runtimeSummary.invalidArtifacts.filter((artifact) =>
+      ["runtime.release", "runtime.decisions"].includes(artifact),
+    ),
+    ...missingArtifacts.filter(
+      (artifact) => artifact === "runtime.release" || artifact === "runtime.decisions",
+    ),
+  ];
+  const runtimeBlockers = [
+    ...runtimeSummary.invalidArtifacts.map((artifact) => `runtime artifact ${artifact} is invalid`),
+    ...missingArtifacts.map((artifact) => `runtime artifact ${artifact} is missing`),
+    ...(runtimeSummary.pendingMailboxCount > 0
+      ? ["pending mailbox proposals require leader review"]
+      : []),
+    ...(runtimeSummary.criticalPackageExposureCount > 0
+      ? [
+          `critical package exposure findings require $vet remediation (${runtimeSummary.criticalPackageExposureCount} active)`,
+        ]
+      : []),
+    ...(runtimeSummary.mcpPolicyViolationCount > 0
+      ? [
+          `MCP policy validation findings require $vet remediation (${runtimeSummary.mcpPolicyViolationCount} active)`,
+        ]
+      : []),
+    ...(enforceIssueGates && runtimeSummary.releaseIssueGateBlockerCount > 0
+      ? [
+          `release issue gates require implementation proof (${runtimeSummary.releaseIssueGatePassed}/${runtimeSummary.releaseIssueGateTotal} passed)`,
+        ]
+      : []),
+  ];
+  const releaseBlockers = formatBuildBlockers(releaseEvaluation);
+  const nextTriggers =
+    releaseEvaluation.allowed && runtimeBlockers.length > 0
+      ? runtimeSummary.criticalPackageExposureCount > 0 ||
+        runtimeSummary.mcpPolicyViolationCount > 0
+        ? ["$vet"]
+        : enforceIssueGates && runtimeSummary.releaseIssueGateBlockerCount > 0
+          ? ["implement release issue gates"]
+          : ["repair runtime artifacts"]
+      : formatNextAllowedTriggers(releaseEvaluation);
+
+  return {
+    allowed: releaseEvaluation.allowed && runtimeBlockers.length === 0,
+    controlPlaneBlockers,
+    runtimeBlockers,
+    releaseBlockers,
+    blockers: [...releaseBlockers, ...runtimeBlockers],
+    nextTriggers,
+  };
+}

package/src/runtime/code-graph-rehearse.js

@@ -0,0 +1,113 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const codeGraphRehearseSchemaVersion = "0.1.0";
+const defaultMaxSteps = 12;
+
+export function getCodeGraphRehearsePath() {
+  return getRuntimeSubsystemPath("context", "code-graph-rehearse.json");
+}
+
+export function createDefaultCodeGraphRehearse() {
+  return {
+    schemaVersion: codeGraphRehearseSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "Provides a bounded read-only trajectory preview over likely code touchpoints before execution.",
+    max_steps: defaultMaxSteps,
+    mutation_policy: {
+      may_mutate_source: false,
+      may_mutate_release_state: false,
+    },
+    evidence_boundary: {
+      records_as: "rehearsal_trace",
+      never_records_as: "implementation_evidence",
+      does_not_unlock: ["source_mutation", "production_release"],
+    },
+    applies_to: ["$arch", "$flow", "$build", "executor_roles"],
+  };
+}
+
+export function validateCodeGraphRehearse(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("code graph rehearse must be an object");
+  }
+  if (value.schemaVersion !== codeGraphRehearseSchemaVersion) {
+    throw new Error(`Unsupported code graph rehearse schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!Number.isInteger(value.max_steps) || value.max_steps <= 0) {
+    throw new Error("code graph rehearse requires positive max_steps");
+  }
+  if (value.mutation_policy?.may_mutate_source !== false) {
+    throw new Error("code graph rehearse must not mutate source");
+  }
+  if (value.evidence_boundary?.records_as !== "rehearsal_trace") {
+    throw new Error("code graph rehearse must record as rehearsal_trace");
+  }
+  return value;
+}
+
+export async function seedCodeGraphRehearseArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getCodeGraphRehearsePath(),
+    `${JSON.stringify(createDefaultCodeGraphRehearse(), null, 2)}\n`,
+  );
+}
+
+export async function loadCodeGraphRehearse() {
+  return validateCodeGraphRehearse(await readJson(getCodeGraphRehearsePath()));
+}
+
+export function createCodeGraphTouchpoint(filePath, imports = []) {
+  return {
+    path: filePath,
+    extension: path.extname(filePath),
+    imports: imports.filter((entry) => typeof entry === "string" && entry.trim()),
+  };
+}
+
+export function extractStaticImports(sourceText) {
+  const imports = new Set();
+  const patterns = [
+    /import\s+(?:[^'"]+\s+from\s+)?["']([^"']+)["']/g,
+    /export\s+[^'"]+\s+from\s+["']([^"']+)["']/g,
+    /await\s+import\(["']([^"']+)["']\)/g,
+    /import\(["']([^"']+)["']\)/g,
+    /require\(["']([^"']+)["']\)/g,
+  ];
+
+  for (const pattern of patterns) {
+    for (const match of sourceText.matchAll(pattern)) {
+      if (match[1]) {
+        imports.add(match[1]);
+      }
+    }
+  }
+
+  return [...imports].sort();
+}
+
+export async function createCodeGraphTouchpointFromFile(filePath) {
+  const sourceText = await fs.readFile(filePath, "utf8");
+  return createCodeGraphTouchpoint(filePath, extractStaticImports(sourceText));
+}
+
+export function createRehearsalTrace({ story, touchpoints = [], plannedSteps = [], maxSteps }) {
+  const limit = Number.isInteger(maxSteps) && maxSteps > 0 ? maxSteps : defaultMaxSteps;
+  const boundedSteps = plannedSteps.slice(0, limit);
+  return {
+    record_type: "rehearsal_trace",
+    story,
+    bounded: plannedSteps.length <= limit,
+    truncated: plannedSteps.length > limit,
+    max_steps: limit,
+    steps: boundedSteps,
+    touchpoints,
+    source_mutation_allowed: false,
+    production_evidence: false,
+    does_not_unlock: ["source_mutation", "production_release"],
+  };
+}

package/src/runtime/context-economy-core.js

@@ -0,0 +1,276 @@
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const contextEconomySchemaVersion = "0.1.0";
+
+const safetySignals = [
+  "security warning",
+  "irreversible",
+  "destructive",
+  "credential",
+  "verification failed",
+  "validation failed",
+  "user confused",
+];
+
+const removableWords = new Set([
+  "a",
+  "an",
+  "the",
+  "just",
+  "really",
+  "basically",
+  "sure",
+  "happy",
+  "glad",
+]);
+
+export function getContextEconomyCorePath() {
+  return getRuntimeSubsystemPath("context", "context-economy-core.json");
+}
+
+export function createDefaultContextEconomyCore() {
+  return {
+    schemaVersion: contextEconomySchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "MA-owned default context compression policy for terse progress, summaries, MCP descriptors, and exported host payloads.",
+    style: "compact_technical",
+    evidence_source: {
+      repo: "JuliusBrussee/caveman",
+      endpoint: "https://gitmcp.io/JuliusBrussee/caveman",
+      applied_as: "MA Context Economy Core",
+      adoption_boundary:
+        "Use the compression and auto-clarity contract as core MA behavior without adopting third-party persona branding.",
+    },
+    applies_to: [
+      "$maestro",
+      "gated_lanes",
+      "helper_skills",
+      "executor_roles",
+      "reviewer_roles",
+      "verifier_roles",
+      "team_workers",
+      "mcp_descriptors",
+      "exported_host_payloads",
+    ],
+    preserve_exact: [
+      "code_blocks",
+      "commands",
+      "schemas",
+      "security_warnings",
+      "authority_fields",
+      "verification_failures",
+      "known_gaps",
+      "commit_messages",
+    ],
+    safety_valves: safetySignals,
+    compression_rules: [
+      "Remove filler and pleasantries from progress, summaries, and descriptors.",
+      "Fragments are allowed when meaning stays exact.",
+      "Keep technical nouns, commands, paths, code, schemas, evidence status, and blockers exact.",
+      "Use auto-clarity bypass for safety warnings, irreversible actions, failed checks, credentials, and confused users.",
+    ],
+    hard_rules: [
+      "Context Economy is default MA behavior, not a third-party persona.",
+      "Technical terms, code, schemas, commands, warnings, and evidence boundaries stay exact.",
+      "Disable compression when safety, authority, or user clarity would degrade.",
+    ],
+  };
+}
+
+function compactPlainText(text) {
+  return text
+    .split(/\s+/)
+    .filter((word) => !removableWords.has(word.toLowerCase().replace(/[^a-z]/g, "")))
+    .join(" ")
+    .replace(/\s+([,.;:!?])/g, "$1")
+    .trim();
+}
+
+export function shouldBypassContextEconomy({ text = "", tags = [] } = {}) {
+  const haystack = `${text} ${tags.join(" ")}`.toLowerCase();
+  return safetySignals.some((signal) => haystack.includes(signal));
+}
+
+export function createContextEconomyView({ text, tags = [], level = "core" }) {
+  if (typeof text !== "string") {
+    throw new Error("Context Economy view requires text");
+  }
+
+  const bypassed = shouldBypassContextEconomy({ text, tags });
+  const parts = text.split(/(```[\s\S]*?```)/g);
+  const output = bypassed
+    ? text
+    : parts
+        .map((part) => (part.startsWith("```") ? part : compactPlainText(part)))
+        .join("")
+        .trim();
+
+  return {
+    record_type: "context_economy_view",
+    level,
+    bypassed,
+    records_as: "context_budget",
+    original_chars: text.length,
+    output_chars: output.length,
+    output,
+    preserved_exact: ["code_blocks", "commands", "warnings", "schemas", "authority_fields"],
+  };
+}
+
+export function createContextEconomyPayload({
+  surface = "$maestro",
+  payload = {},
+  tags = [],
+  level = "core",
+} = {}) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("Context Economy payload requires an object payload");
+  }
+
+  const transformed = {};
+  const fields = [];
+  for (const [key, value] of Object.entries(payload)) {
+    const result = transformContextEconomyValue({ key, value, tags, level });
+    transformed[key] = result.value;
+    fields.push({
+      key,
+      compressed: result.compressed,
+      bypassed: result.bypassed,
+      original_chars: result.originalChars,
+      output_chars: result.outputChars,
+    });
+  }
+
+  return {
+    record_type: "context_economy_payload",
+    surface,
+    level,
+    records_as: "context_budget",
+    build_evidence: false,
+    payload: transformed,
+    fields,
+    preserved_exact: [
+      "code",
+      "commands",
+      "paths",
+      "schemas",
+      "authority_fields",
+      "security_warnings",
+      "verification_evidence",
+    ],
+  };
+}
+
+export function createMcpDescriptorEconomy({ name, description, inputSchema = {}, tags = [] }) {
+  if (!name || typeof name !== "string") {
+    throw new Error("MCP descriptor economy requires a tool name");
+  }
+  const compacted = createContextEconomyView({
+    text: description ?? "",
+    tags,
+    level: "mcp_descriptor",
+  });
+  return {
+    record_type: "mcp_descriptor_economy",
+    records_as: "context_budget",
+    build_evidence: false,
+    name,
+    description: compacted.output,
+    inputSchema,
+    bypassed: compacted.bypassed,
+    preserved_exact: ["name", "inputSchema"],
+  };
+}
+
+export function validateContextEconomyCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Context Economy core must be an object");
+  }
+  if (value.schemaVersion !== contextEconomySchemaVersion) {
+    throw new Error(`Unsupported Context Economy schemaVersion: ${value.schemaVersion}`);
+  }
+  if (value.evidence_source?.repo !== "JuliusBrussee/caveman") {
+    throw new Error("Context Economy core requires Caveman evidence source mapping");
+  }
+  for (const required of ["code_blocks", "security_warnings", "authority_fields"]) {
+    if (!value.preserve_exact?.includes(required)) {
+      throw new Error(`Context Economy core must preserve ${required}`);
+    }
+  }
+  if (!value.compression_rules?.some((rule) => rule.includes("auto-clarity bypass"))) {
+    throw new Error("Context Economy core requires auto-clarity compression rule");
+  }
+  for (const signal of ["security warning", "irreversible", "verification failed"]) {
+    if (!value.safety_valves?.includes(signal)) {
+      throw new Error(`Context Economy core requires ${signal} safety valve`);
+    }
+  }
+  if (JSON.stringify(value).includes(".omx")) {
+    throw new Error("Context Economy core must not expose OMX runtime paths");
+  }
+  return value;
+}
+
+function transformContextEconomyValue({ key, value, tags, level }) {
+  if (typeof value !== "string") {
+    return {
+      value,
+      compressed: false,
+      bypassed: false,
+      originalChars: 0,
+      outputChars: 0,
+    };
+  }
+  if (shouldPreserveField(key)) {
+    return {
+      value,
+      compressed: false,
+      bypassed: true,
+      originalChars: value.length,
+      outputChars: value.length,
+    };
+  }
+  const view = createContextEconomyView({ text: value, tags, level });
+  return {
+    value: view.output,
+    compressed: !view.bypassed && view.output !== value,
+    bypassed: view.bypassed,
+    originalChars: view.original_chars,
+    outputChars: view.output_chars,
+  };
+}
+
+function shouldPreserveField(key) {
+  const normalized = key.toLowerCase();
+  return [
+    "code",
+    "command",
+    "commands",
+    "schema",
+    "inputschema",
+    "path",
+    "paths",
+    "authority",
+    "authority_boundary",
+    "security_warning",
+    "warning",
+    "verification_evidence",
+    "evidence",
+    "known_gap",
+    "known_gaps",
+  ].includes(normalized);
+}
+
+export async function seedContextEconomyCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getContextEconomyCorePath(),
+    `${JSON.stringify(createDefaultContextEconomyCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadContextEconomyCore() {
+  return validateContextEconomyCore(await readJson(getContextEconomyCorePath()));
+}

package/src/runtime/continuity-notes.js

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+import { guardLeaderMutation } from "./runtime-state.js";
+
+export function getContinuityRoot() {
+  return getRuntimeSubsystemPath("memory");
+}
+
+export function getContinuityNotesPath() {
+  return getRuntimeSubsystemPath("memory", "notes.md");
+}
+
+export function getContinuityIndexPath() {
+  return getRuntimeSubsystemPath("memory", "index.json");
+}
+
+export async function seedContinuityArtifacts() {
+  await ensureDir(getContinuityRoot());
+  await writeFileIfMissing(
+    getContinuityNotesPath(),
+    "# Continuity Notes\n\nNo continuity notes captured yet.\n",
+  );
+  await writeFileIfMissing(
+    getContinuityIndexPath(),
+    `${JSON.stringify(
+      {
+        schemaVersion: "0.1.0",
+        sessionCount: 0,
+        lastUpdatedAt: null,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+export async function loadContinuityNotes() {
+  return fs.readFile(getContinuityNotesPath(), "utf8");
+}
+
+export async function loadContinuityIndex() {
+  return readJson(getContinuityIndexPath());
+}
+
+export async function storeContinuityNote(content, options = {}) {
+  const guard = await guardLeaderMutation({
+    actor: options.actor,
+    kind: "memory-note-write",
+    payload: { content },
+  });
+  if (!guard.allowed) {
+    return { proposed: true, proposalPath: guard.proposalPath };
+  }
+
+  const note = content.trim();
+  if (!note) {
+    throw new Error("memory.store_note requires non-empty content");
+  }
+
+  const [existingNotes, existingIndex] = await Promise.all([
+    loadContinuityNotes(),
+    loadContinuityIndex(),
+  ]);
+  const timestamp = new Date().toISOString();
+  const nextNotes = `${existingNotes.trimEnd()}\n\n## ${timestamp}\n\n${note}\n`;
+  const nextIndex = {
+    ...existingIndex,
+    sessionCount: existingIndex.sessionCount + 1,
+    lastUpdatedAt: timestamp,
+  };
+
+  await Promise.all([
+    fs.writeFile(getContinuityNotesPath(), nextNotes),
+    writeJson(getContinuityIndexPath(), nextIndex),
+  ]);
+
+  return { proposed: false, proposalPath: null, index: nextIndex };
+}