@jstn-sdk/ma 0.1.12 → 0.14.0

package/src/runtime/context-authority.js

@@ -0,0 +1,40 @@
+export const contextAuthorityOrder = [
+  "source_truth",
+  "verified_evidence",
+  "hook_evidence",
+  "generated_context",
+  "vault_note",
+  "learning_memory",
+  "external_reference",
+  "stale",
+];
+
+export function createFreshness({
+  sourceHash = null,
+  sourceFiles = [],
+  checkedAt = new Date().toISOString(),
+  status = "fresh",
+} = {}) {
+  return {
+    status,
+    stale: status === "stale",
+    checkedAt,
+    sourceHash,
+    sourceFiles: [...sourceFiles],
+    changedFiles: [...sourceFiles],
+  };
+}
+
+export function resolveContextConflict(candidates = []) {
+  return (
+    [...candidates]
+      .filter((candidate) => candidate && typeof candidate === "object")
+      .sort((left, right) => {
+        const authority =
+          contextAuthorityOrder.indexOf(left.authority) -
+          contextAuthorityOrder.indexOf(right.authority);
+        if (authority !== 0) return authority;
+        return Number(Boolean(left.freshness?.stale)) - Number(Boolean(right.freshness?.stale));
+      })[0] ?? null
+  );
+}

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

@@ -0,0 +1,316 @@
+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 createBudgetedContext({ items = [], budgetChars = 12000, topic } = {}) {
+  const candidates = items
+    .filter((item) => item && typeof item.id === "string" && typeof item.text === "string")
+    .map((item, index) => ({ ...item, tier: item.tier ?? index }));
+  const topical = topic
+    ? candidates.filter((item) =>
+        `${item.topic ?? ""} ${item.id}`.toLowerCase().includes(topic.toLowerCase()),
+      )
+    : candidates;
+  const pool = topical.length > 0 ? topical : candidates;
+  let remaining = Math.max(0, budgetChars);
+  const loaded = [];
+  const skipped = candidates
+    .filter((item) => !pool.includes(item))
+    .map((item) => ({ id: item.id, reason: "topic_mismatch" }));
+  const context = {};
+
+  for (const item of [...pool].sort((left, right) => left.tier - right.tier)) {
+    const view = createContextEconomyView({ text: item.text, level: "budgeted_context" });
+    if (view.output_chars <= remaining) {
+      context[item.id] = view.output;
+      remaining -= view.output_chars;
+      loaded.push(item.id);
+    } else {
+      skipped.push({ id: item.id, reason: "budget_exhausted" });
+    }
+  }
+
+  return {
+    record_type: "budgeted_context",
+    budget_chars: budgetChars,
+    used_chars: budgetChars - remaining,
+    topic: topic ?? null,
+    loaded,
+    skipped,
+    fallback_expanded: Boolean(topic && topical.length === 0),
+    context,
+  };
+}
+
+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-graph.js

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const continuityGraphSchemaVersion = "0.1.0";
+
+export function getContinuityGraphPath() {
+  return getRuntimeSubsystemPath("memory", "graph.json");
+}
+
+export function createDefaultContinuityGraph() {
+  return {
+    schemaVersion: continuityGraphSchemaVersion,
+    record_type: "continuity_knowledge_graph",
+    humanReadableMirror: ".ma/memory/notes.md",
+    nodes: [],
+    edges: [],
+    lastUpdatedAt: null,
+  };
+}
+
+export function validateContinuityGraph(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("continuity graph must be an object");
+  }
+  if (value.schemaVersion !== continuityGraphSchemaVersion) {
+    throw new Error(`Unsupported continuity graph schemaVersion: ${value.schemaVersion}`);
+  }
+  if (value.record_type !== "continuity_knowledge_graph") {
+    throw new Error("continuity graph has an invalid record_type");
+  }
+  if (!Array.isArray(value.nodes) || !Array.isArray(value.edges)) {
+    throw new Error("continuity graph requires nodes and edges arrays");
+  }
+  for (const node of value.nodes) {
+    if (
+      !node ||
+      typeof node !== "object" ||
+      typeof node.id !== "string" ||
+      typeof node.type !== "string" ||
+      typeof node.label !== "string" ||
+      typeof node.scope !== "string" ||
+      !Number.isInteger(node.mentions) ||
+      node.mentions < 0
+    ) {
+      throw new Error("continuity graph contains an invalid node");
+    }
+  }
+  const nodeIds = new Set(value.nodes.map((node) => node.id));
+  for (const edge of value.edges) {
+    if (
+      !edge ||
+      typeof edge !== "object" ||
+      typeof edge.id !== "string" ||
+      typeof edge.source !== "string" ||
+      typeof edge.target !== "string" ||
+      typeof edge.relation !== "string" ||
+      !nodeIds.has(edge.source) ||
+      !nodeIds.has(edge.target)
+    ) {
+      throw new Error("continuity graph contains an invalid edge");
+    }
+  }
+  return value;
+}
+
+export async function seedContinuityGraphArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("memory"));
+  await writeFileIfMissing(
+    getContinuityGraphPath(),
+    `${JSON.stringify(createDefaultContinuityGraph(), null, 2)}\n`,
+  );
+}
+
+export async function loadContinuityGraph() {
+  return validateContinuityGraph(await readJson(getContinuityGraphPath()));
+}
+
+function stableId(prefix, value) {
+  return `${prefix}:${createHash("sha256").update(value).digest("hex").slice(0, 16)}`;
+}
+
+function deriveEntities(content, explicit = []) {
+  const values = [
+    ...explicit,
+    ...(content.match(/`([^`]+)`|#([a-z][\w-]*)|\b[A-Z][A-Za-z0-9_-]{2,}\b/g) ?? []),
+  ]
+    .map((value) => value.replaceAll("`", "").replace(/^#/, "").trim().toLowerCase())
+    .filter((value) => value.length >= 3 && value.length <= 80);
+  return [...new Set(values)].slice(0, 32);
+}
+
+export function mergeContinuityGraph(
+  graph,
+  { content, scope, timestamp, entities = [], relationships = [] },
+) {
+  const next = validateContinuityGraph(graph);
+  const noteId = stableId("note", `${timestamp}\0${scope}\0${content}`);
+  const entityNames = deriveEntities(content, entities);
+  const nodes = [...next.nodes];
+  const edges = [...next.edges];
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const edgeKeys = new Set(edges.map((edge) => `${edge.source}\0${edge.target}\0${edge.relation}`));
+  const addNode = (node) => {
+    const existing = nodeById.get(node.id);
+    if (existing) {
+      existing.updatedAt = timestamp;
+      existing.mentions = (existing.mentions ?? 0) + (node.mentions ?? 0);
+      return;
+    }
+    nodeById.set(node.id, node);
+    nodes.push(node);
+  };
+  const addEdge = (source, target, relation) => {
+    const key = `${source}\0${target}\0${relation}`;
+    if (source === target || edgeKeys.has(key)) return;
+    edgeKeys.add(key);
+    edges.push({ id: stableId("edge", key), source, target, relation, updatedAt: timestamp });
+  };
+
+  addNode({
+    id: noteId,
+    type: "session",
+    label: `${scope} note`,
+    scope,
+    mentions: 1,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  });
+  const entityIds = entityNames.map((name) => {
+    const id = stableId("entity", name);
+    addNode({
+      id,
+      type: "entity",
+      label: name,
+      scope,
+      mentions: 1,
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    });
+    addEdge(noteId, id, "mentions");
+    return id;
+  });
+  for (let index = 0; index < entityIds.length; index += 1) {
+    for (let other = index + 1; other < entityIds.length; other += 1)
+      addEdge(entityIds[index], entityIds[other], "co_occurs");
+  }
+  for (const relationship of relationships) {
+    if (!relationship || typeof relationship !== "object") continue;
+    const from = stableId("entity", String(relationship.from ?? "").toLowerCase());
+    const to = stableId("entity", String(relationship.to ?? "").toLowerCase());
+    if (nodeById.has(from) && nodeById.has(to) && relationship.relation)
+      addEdge(from, to, String(relationship.relation));
+  }
+  return {
+    ...next,
+    nodes: nodes.slice(-1000),
+    edges: edges.slice(-4000),
+    lastUpdatedAt: timestamp,
+  };
+}
+
+export function queryContinuityGraph(graph, { nodeId, label, depth = 2, limit = 100 } = {}) {
+  const value = validateContinuityGraph(graph);
+  const normalizedLabel = label?.trim().toLowerCase();
+  const boundedLimit = Math.max(1, Math.min(Number(limit) || 100, 1000));
+  const starts = value.nodes.filter(
+    (node) =>
+      node.id === nodeId || (normalizedLabel && node.label.toLowerCase() === normalizedLabel),
+  );
+  if (starts.length === 0) return { nodes: [], edges: [], depth: 0 };
+  const included = new Set(starts.map((node) => node.id));
+  let frontier = [...included];
+  const maxDepth = Math.max(0, Math.min(Number(depth) || 0, 5));
+  for (let level = 0; level < maxDepth; level += 1) {
+    const next = [];
+    for (const edge of value.edges) {
+      if (frontier.includes(edge.source) && !included.has(edge.target)) next.push(edge.target);
+      if (frontier.includes(edge.target) && !included.has(edge.source)) next.push(edge.source);
+    }
+    frontier = [...new Set(next)].slice(0, boundedLimit);
+    frontier.forEach((id) => {
+      included.add(id);
+    });
+    if (frontier.length === 0) break;
+  }
+  const nodes = value.nodes.filter((node) => included.has(node.id)).slice(0, boundedLimit);
+  const ids = new Set(nodes.map((node) => node.id));
+  return {
+    nodes,
+    edges: value.edges.filter((edge) => ids.has(edge.source) && ids.has(edge.target)),
+    depth: maxDepth,
+  };
+}
+
+export async function mergeContinuityGraphEntry(entry) {
+  const graph = await loadContinuityGraph();
+  const next = mergeContinuityGraph(graph, entry);
+  await writeJson(getContinuityGraphPath(), next);
+  return next;
+}

package/src/runtime/continuity-notes.js

@@ -1,8 +1,25 @@
 import fs from "node:fs/promises";
-import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import path from "node:path";
+import {
+  ensureDir,
+  readJson,
+  writeFileIfMissing,
+  writeJson,
+  writeTextAtomically,
+} from "../fs-utils.js";
 import { getRuntimeSubsystemPath } from "../paths.js";
+import { mergeContinuityGraphEntry, seedContinuityGraphArtifacts } from "./continuity-graph.js";
 import { guardLeaderMutation } from "./runtime-state.js";
 
+export const knowledgeScopes = ["personal/local", "project-shared", "team/process", "session-only"];
+let continuityWriteQueue = Promise.resolve();
+const scopeFiles = {
+  "personal/local": "personal.md",
+  "project-shared": "notes.md",
+  "team/process": "team.md",
+  "session-only": "session.md",
+};
+
 export function getContinuityRoot() {
   return getRuntimeSubsystemPath("memory");
 }
@@ -21,6 +38,13 @@ export async function seedContinuityArtifacts() {
     getContinuityNotesPath(),
     "# Continuity Notes\n\nNo continuity notes captured yet.\n",
   );
+  await seedContinuityGraphArtifacts();
+  for (const file of ["personal.md", "team.md", "session.md"]) {
+    await writeFileIfMissing(
+      path.join(getContinuityRoot(), file),
+      `# ${file.replace(".md", "")} knowledge\n\nNo notes captured yet.\n`,
+    );
+  }
   await writeFileIfMissing(
     getContinuityIndexPath(),
     `${JSON.stringify(
@@ -28,6 +52,7 @@ export async function seedContinuityArtifacts() {
         schemaVersion: "0.1.0",
         sessionCount: 0,
         lastUpdatedAt: null,
+        knowledgeScopes,
       },
       null,
       2,
@@ -36,7 +61,17 @@ export async function seedContinuityArtifacts() {
 }
 
 export async function loadContinuityNotes() {
-  return fs.readFile(getContinuityNotesPath(), "utf8");
+  return loadScopedKnowledge({ scopes: ["project-shared", "team/process"] });
+}
+
+export async function loadScopedKnowledge({ scopes = ["project-shared", "team/process"] } = {}) {
+  const selected = scopes.filter((scope) => knowledgeScopes.includes(scope));
+  const notes = await Promise.all(
+    selected.map((scope) =>
+      fs.readFile(path.join(getContinuityRoot(), scopeFiles[scope]), "utf8").catch(() => ""),
+    ),
+  );
+  return notes.filter(Boolean).join("\n\n");
 }
 
 export async function loadContinuityIndex() {
@@ -47,33 +82,43 @@ export async function storeContinuityNote(content, options = {}) {
   const guard = await guardLeaderMutation({
     actor: options.actor,
     kind: "memory-note-write",
-    payload: { content },
+    payload: { content, scope: options.scope ?? "session-only" },
   });
   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 };
+  const operation = continuityWriteQueue.then(async () => {
+    const note = content.trim();
+    if (!note) throw new Error("memory.store_note requires non-empty content");
+    const scope = options.scope ?? "project-shared";
+    if (!knowledgeScopes.includes(scope)) throw new Error(`Unsupported knowledge scope: ${scope}`);
+    const [existingNotes, existingIndex] = await Promise.all([
+      fs.readFile(path.join(getContinuityRoot(), scopeFiles[scope]), "utf8").catch(() => ""),
+      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,
+      scopeCounts: {
+        ...(existingIndex.scopeCounts ?? {}),
+        [scope]: (existingIndex.scopeCounts?.[scope] ?? 0) + 1,
+      },
+    };
+    await writeTextAtomically(path.join(getContinuityRoot(), scopeFiles[scope]), nextNotes);
+    await writeJson(getContinuityIndexPath(), nextIndex);
+    await mergeContinuityGraphEntry({
+      content: note,
+      scope,
+      timestamp,
+      entities: options.entities,
+      relationships: options.relationships,
+    });
+    return { proposed: false, proposalPath: null, index: nextIndex };
+  });
+  continuityWriteQueue = operation.catch(() => {});
+  return operation;
 }