b2c-app-builder 0.221.39

package/kernel/knowledge-service/tools.ts

@@ -0,0 +1,118 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { KnowledgeServiceError, catalogInputSchema, knowledgeGetInputSchema, knowledgeSearchInputSchema, workflowInputSchema } from "./service.js";
+import type { HostedKnowledgeResult, KnowledgeService } from "./types.js";
+
+const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } as const;
+
+/** Shared schemas are strict objects. HTTP must call the same service as MCP. */
+export const KNOWLEDGE_TOOL_DEFINITIONS = [
+  {
+    name: "b2c_catalog",
+    title: "Browse B2C App Builder workflows",
+    description:
+      "Browse the versioned workflow catalog. Filter by query or domain ID and paginate. This reads guidance; it does not plan or run a workspace. " +
+      "The default page keeps domains as an empty array and adds domainCounts (per-domain workflow totals, always present, counted over the whole catalog, not the current page). " +
+      'Pass include="domains" for the full domain objects, on any page or offset. ' +
+      "Compatibility: domains is always present, so a reader never sees it as undefined. The response also includes a schemaVersion field. The hosted HTTP surface (GET /api/v1/catalog) returns this same JSON shape. " +
+      'Measured on the shipped catalog: a default page (no query/domainId, limit=20) serializes at 9549 bytes. domainCounts adds 729 bytes to that total. The full domain array under include="domains" is 3077 bytes.',
+    inputSchema: catalogInputSchema,
+    annotations,
+  },
+  {
+    name: "b2c_workflow",
+    title: "Read a B2C App Builder workflow",
+    description:
+      "Get a compact workflow route by stable workflowId. The default include=route omits working instructions and knowledge bodies. " +
+      "route.outputs links each indexed artifact specification to its exact section call and validator; route.references carries bounded section discovery and revision-pinned retrieval. " +
+      "Read the required guidance before work. A route is not evidence that it was delivered or read. route.coverage.delivery and warnings name missing delivery. " +
+      "Use include=instructions for the complete working instructions without a knowledge bundle. Use brief:true only when an expanded dispatch packet is needed. " +
+      "Opt-in include=summaries or full retains the bounded bundle allocator. tokenBudget counts Unicode code points, not measured tokens, and is valid only for those two modes. " +
+      "Follow coverage.incomplete and nextOffset on explicit bundles; prefer exact sections over a large bundle. " +
+      "continuation lists dependency relationships, not an executable workspace plan or permission to skip review. A workflow pass cannot declare a business complete.",
+    inputSchema: workflowInputSchema,
+    annotations,
+  },
+  {
+    name: "b2c_knowledge_search",
+    title: "Search B2C App Builder knowledge",
+    description:
+      "Search active knowledge by a bounded query (1-200 characters) and optional domain ID. Paginate with offset (same 0-10000 offset as b2c_catalog) and limit (1-20, default 10). " +
+      "Pass workflowId to traverse that workflow's authored reference bindings: lexical matches lead, followed by related guidance labelled match.kind=workflow_binding. " +
+      "workflowCoverage lists all bound IDs and any excluded by a domain filter; an excerpt is never proof that the full required guidance was read. " +
+      "Each result carries a bounded excerpt and, when available, section.get with exact revision-pinned retrieval arguments. An excerpt is not the full required guidance.",
+    inputSchema: knowledgeSearchInputSchema,
+    annotations,
+  },
+  {
+    name: "b2c_knowledge_get",
+    title: "Read B2C App Builder knowledge",
+    description:
+      "Get active Markdown by stable referenceId, never by path. Use a discovered sectionId plus expectedContentSha256 for exact sections, including descendant headings. " +
+      "Offsets count Unicode code points within the selected section (or the whole document without sectionId). Follow nextCall. Stale hashes and unknown sections refuse. " +
+      "view=sections with expectedContentSha256 returns a paginated heading index without a body; use sectionOffset and sectionLimit for that index. Returns hashes and source provenance.",
+    inputSchema: knowledgeGetInputSchema,
+    annotations,
+  },
+] as const;
+
+export type KnowledgeToolName = (typeof KNOWLEDGE_TOOL_DEFINITIONS)[number]["name"];
+
+export function callKnowledgeTool(service: KnowledgeService, name: string, input: unknown): HostedKnowledgeResult {
+  switch (name) {
+    case "b2c_catalog":
+      return service.catalog(input);
+    case "b2c_workflow":
+      return service.workflow(input);
+    case "b2c_knowledge_search":
+      return service.search(input);
+    case "b2c_knowledge_get":
+      return service.get(input);
+    default:
+      throw new KnowledgeServiceError("not_found", "Knowledge tool was not found.");
+  }
+}
+
+/**
+ * Shared success/error shaping for a knowledge tool call — the same CallToolResult shape whether
+ * `compute` is the shared per-name dispatch (`registerKnowledgeTools`'s own loop) or, on the local
+ * stdio server only, a direct `service.workflow(...)` call inside the local-only extended
+ * b2c_workflow tool (entrypoints/mcp/server.ts) that still needs this exact error shape.
+ */
+export function toCallToolResult(compute: () => HostedKnowledgeResult): CallToolResult {
+  try {
+    const result = compute();
+    return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: { ...result } };
+  } catch (error) {
+    // isRetryable tells the calling agent whether to retry as-is. invalid_arguments and not_found
+    // both need different caller input, not a retry; a future transient code (e.g. a knowledge-
+    // bundle load failure) is the one that should set this true.
+    const result =
+      error instanceof KnowledgeServiceError
+        ? { error: { code: error.code, message: error.message, isRetryable: false } }
+        : { error: { code: "internal_error", message: "Knowledge request failed.", isRetryable: false } };
+    return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result, isError: true };
+  }
+}
+
+/**
+ * Registers every KNOWLEDGE_TOOL_DEFINITIONS entry except those named in `exclude` — the local
+ * stdio server (entrypoints/mcp/server.ts) excludes "b2c_workflow" here and registers its own
+ * workspace-aware superset instead, sharing this same dispatch and error-shaping for every other
+ * name so there is exactly one implementation of "how a knowledge tool call is shaped", not two.
+ */
+export function registerKnowledgeTools(server: McpServer, service: KnowledgeService, options: { exclude?: readonly KnowledgeToolName[] } = {}): void {
+  const excluded = new Set<string>(options.exclude ?? []);
+  for (const definition of KNOWLEDGE_TOOL_DEFINITIONS) {
+    if (excluded.has(definition.name)) continue;
+    server.registerTool(
+      definition.name,
+      { title: definition.title, description: definition.description, inputSchema: definition.inputSchema, annotations: definition.annotations },
+      async (input: unknown): Promise<CallToolResult> => {
+        const result = toCallToolResult(() => callKnowledgeTool(service, definition.name, input));
+        const bulk = input !== null && typeof input === "object" && ["summaries", "full"].includes(String((input as { include?: unknown }).include));
+        return definition.name === "b2c_workflow" && bulk ? { ...result, _meta: { "anthropic/maxResultSizeChars": 500_000 } } : result;
+      },
+    );
+  }
+}

package/kernel/knowledge-service/types.ts

@@ -0,0 +1,236 @@
+import type { KnowledgeSection } from "./sections.js";
+import type { Catalog, CatalogDomainId, CatalogKnowledgeSource, CatalogWorkflowDef, ReferenceId } from "../../catalog/types.js";
+// Type-only: erased at compile time, so importing the NodeBrief shape costs the hosted Worker's
+// actual bundle nothing (kernel/engine/compile.ts, the module NodeBrief's own definition depends on
+// by type, is never pulled in as a value here — see service.ts's buildDispatchBrief for why its
+// verification-policy formula is duplicated rather than imported).
+import type { NodeBrief } from "../engine/node-brief.js";
+
+// 2.0.0 makes workflow discovery route-first and adds revision-bound section addressing.
+// Explicit include="instructions" restores authored workflow instructions; body modes remain opt-in.
+export const HOSTED_KNOWLEDGE_SCHEMA_VERSION = "2.0.0" as const;
+export const MAX_HOSTED_DOCUMENT_BYTES = 256 * 1024;
+export const MAX_HOSTED_BUNDLE_BYTES = 8 * 1024 * 1024;
+export const MAX_KNOWLEDGE_PAGE_LENGTH = 16_384;
+export const MAX_KNOWLEDGE_EXCERPT_LENGTH = 512;
+/** Unicode code points. A summary is a strict prefix of `markdown`, generated once at render time (tooling/render-hosted-bundle.ts) and pinned into bundleSha256 — never computed per request. */
+export const MAX_HOSTED_REFERENCE_SUMMARY_LENGTH = 800;
+/**
+ * Unicode code points. Applied when a b2c_workflow bundle request (`include`) omits `tokenBudget`.
+ * Matches kernel/engine/compile.ts's DEFAULT_TOKEN_BUDGET (a distinct unit — that one estimates real
+ * LLM tokens for a dispatched node's execution budget) only by coincidence of a round number; the
+ * two are not the same measurement and are not kept in sync.
+ */
+export const DEFAULT_WORKFLOW_BUNDLE_TOKEN_BUDGET = 8_000;
+/**
+ * Unicode code points. Schema ceiling on `tokenBudget`, chosen so the worst real single-workflow
+ * bundle stays safely under hosted/knowledge-mcp/http.ts's MAX_HOSTED_RESPONSE_BYTES (524,288 bytes) —
+ * measured: at this budget, the whole b2c_workflow response for the catalog's largest
+ * reference-total workflow (workflow, guardrails, knowledge[] summaries, and the full
+ * knowledgeBundle together) serializes at 207,942 bytes, under 40% of the ceiling (see the
+ * hosted-knowledge fixture that pins this exact measurement). Not imported from
+ * hosted/knowledge-mcp/http.ts: this module allows no such dependency (see createKnowledgeService's own
+ * "no filesystem, workspace, clock, network, or execution dependency" invariant below).
+ */
+export const MAX_WORKFLOW_BUNDLE_TOKEN_BUDGET = 200_000;
+
+export interface HostedKnowledgeDocument {
+  referenceId: ReferenceId;
+  markdown: string;
+  /** A strict code-point prefix of `markdown`, capped at MAX_HOSTED_REFERENCE_SUMMARY_LENGTH — never a heading extraction, so `nextOffset` continuation into the full document (via b2c_knowledge_get) stays valid at any depth. */
+  summary: string;
+  contentSha256: string;
+  sections?: KnowledgeSection[];
+  sourceMediaType: "text/markdown" | "application/yaml";
+  sourceSha256: string;
+  manifestPath: string;
+  manifestSha256: string;
+}
+
+export interface HostedKnowledgeMetadata {
+  schemaVersion: typeof HOSTED_KNOWLEDGE_SCHEMA_VERSION;
+  engineVersion: string;
+  catalogSha256: string;
+  bundleSha256: string;
+}
+
+/** Build-time data only. Sources and reference metadata occur once, in the catalog. */
+export interface HostedKnowledgeBundle extends HostedKnowledgeMetadata {
+  catalog: Catalog;
+  documents: HostedKnowledgeDocument[];
+}
+
+export interface KnowledgePagination {
+  offset: number;
+  limit: number;
+  total: number;
+  nextOffset: number | null;
+}
+
+export interface HostedReferenceSummary {
+  referenceId: ReferenceId;
+  title: string;
+  domainId: CatalogDomainId;
+  loadWhen: string;
+  contentSha256: string;
+  contentLength: number;
+}
+
+export interface HostedCatalogResult extends HostedKnowledgeMetadata {
+  kind: "catalog";
+  scope: "knowledge_only";
+  /** Empty unless the request set include="domains"; always present so undefined is never read. */
+  domains: Array<{ domainId: CatalogDomainId; title: string; routeWhen: string }>;
+  /** Always present, counted over every workflow in the catalog, not just the current page. */
+  domainCounts: Array<{ domainId: CatalogDomainId; workflowCount: number }>;
+  counts: { workflows: number; references: number };
+  workflows: Array<Pick<CatalogWorkflowDef, "id" | "title" | "domainId" | "trigger" | "referenceIds">>;
+  pagination: KnowledgePagination;
+}
+
+/** One bound reference at the requested depth, sliced from a shared per-workflow token budget. */
+export interface HostedWorkflowBundleReference {
+  referenceId: ReferenceId;
+  /** Fingerprint of the complete document, not the prefix returned in this bundle. */
+  contentSha256: string;
+  contentLength: number;
+  /** Includes source review dates. This is provenance, not a live source freshness claim. */
+  provenance: HostedKnowledgeGetResult["provenance"];
+  depth: "summary" | "full";
+  /** A prefix of the reference's Markdown; may be shorter than the full text at this depth once the shared budget is spent. */
+  markdown: string;
+  /** Unicode code points in `markdown` above — always Array.from(markdown).length, never a byte count. */
+  chars: number;
+  /** True whenever more content exists beyond `markdown` at offset `nextOffset` in the full document — including a fully-delivered summary of a longer document. */
+  truncated: boolean;
+  /** Pass straight to b2c_knowledge_get({ referenceId, offset: nextOffset }) to continue into the full document; null once nothing remains. */
+  nextOffset: number | null;
+}
+
+/** A workflow's bound-reference content, greedily allocated in workflow.referenceIds order against one shared token budget. Every bound reference appears — a budget-exhausted entry reports zero chars, never a silent omission. */
+export interface HostedWorkflowKnowledgeBundle {
+  requestedInclude: "summaries" | "full";
+  tokenBudget: number;
+  budgetUnit: "unicode_code_points";
+  /** Sum of every reference's `chars` in this bundle. */
+  consumedChars: number;
+  references: HostedWorkflowBundleReference[];
+  /** Full-document delivery coverage. Summaries and prefixes never establish complete reading. */
+  coverage: {
+    complete: boolean;
+    /** Every directly bound reference is required; catalog order is not a permission to omit one. */
+    requiredReferenceIds: ReferenceId[];
+    incomplete: Array<{
+      referenceId: ReferenceId;
+      status: "omitted" | "truncated";
+      /** Continue with b2c_knowledge_get({ referenceId, offset }); compare the complete-document hash. */
+      offset: number;
+      contentSha256: string;
+    }>;
+  };
+}
+
+export interface KnowledgeResolver {
+  referenceId: ReferenceId;
+  expectedContentSha256: string;
+  sectionId?: string;
+  offset?: number;
+  view?: "sections";
+  sectionOffset?: number;
+  sectionLimit?: number;
+}
+
+export interface WorkflowKnowledgeRoute {
+  mode: "route" | "instructions" | "summaries" | "full";
+  instructionsIncluded: boolean;
+  expand: { workflowId: string; include: "instructions" };
+  references: Array<{ purpose: string; get: KnowledgeResolver; sections: Array<{ id: string; title: string }> }>;
+  outputs: Array<{ path: string; specifications: Array<{ get: KnowledgeResolver }>; validators: string[]; specificationAvailable: boolean }>;
+  continuation: { dependencies: string[]; successors: string[]; executionAvailable: false; businessComplete: false };
+  coverage: {
+    /** True when this response delivered every required reference in full. Not a caller-reading ledger. */
+    complete: boolean;
+    requiredCount: number;
+    /** Per-response delivery statement. Does not say whether the caller read or finished the work. */
+    delivery: string;
+    incomplete: Array<
+      | { referenceId: ReferenceId; status: "not_requested" }
+      | { referenceId: ReferenceId; status: "omitted" | "truncated"; offset: number; contentSha256: string }
+    >;
+  };
+  warnings: string[];
+}
+
+export interface HostedWorkflowResult extends HostedKnowledgeMetadata {
+  kind: "workflow";
+  scope: "knowledge_only";
+  workflow: CatalogWorkflowDef;
+  knowledge: HostedReferenceSummary[];
+  route: WorkflowKnowledgeRoute;
+  guardrails: {
+    executionAvailable: false;
+    workspacePlan: false;
+    founderOnlyActions: string[];
+    actionClass: CatalogWorkflowDef["actionClass"];
+    protectedCategory?: CatalogWorkflowDef["protectedCategory"];
+  };
+  /** Present only when the request set `include`; null so existing consumers never read undefined. */
+  knowledgeBundle: HostedWorkflowKnowledgeBundle | null;
+  /** Present only when the request set `brief: true`; null so existing consumers never read undefined. Workspace-free — never carries a cwd, a workspace id, or any filesystem fact (that facet exists only on the local-only extended b2c_workflow tool, entrypoints/mcp/server.ts). */
+  dispatchBrief: NodeBrief | null;
+}
+
+export interface HostedKnowledgeSearchResult extends HostedKnowledgeMetadata {
+  kind: "knowledge_search";
+  scope: "knowledge_only";
+  query: string;
+  results: Array<
+    HostedReferenceSummary & {
+      excerpt: string;
+      excerptOffset: number;
+      section?: { id: string; title: string; get: KnowledgeResolver };
+      /** Present for an explicit workflow scope; a binding match is related guidance, not a lexical hit. */
+      match?: { kind: "lexical" | "workflow_binding"; workflowId: string };
+    }
+  >;
+  pagination: KnowledgePagination;
+  /** Present only for workflow-scoped retrieval; domain filtering must not silently hide bound guidance. */
+  workflowCoverage?: {
+    workflowId: string;
+    requiredReferenceIds: ReferenceId[];
+    excludedByDomainReferenceIds: ReferenceId[];
+  };
+}
+
+export interface HostedKnowledgeGetResult extends HostedKnowledgeMetadata {
+  kind: "knowledge";
+  scope: "knowledge_only";
+  reference: HostedReferenceSummary;
+  markdown: string;
+  pagination: KnowledgePagination;
+  paginationUnit: "unicode_code_points";
+  section?: KnowledgeSection;
+  sections?: { items: KnowledgeSection[]; pagination: KnowledgePagination; paginationUnit: "sections" };
+  documentOffset?: number;
+  nextCall?: KnowledgeResolver | null;
+  provenance: {
+    documentPath: string;
+    manifestPath: string;
+    manifestSha256: string;
+    sourceMediaType: HostedKnowledgeDocument["sourceMediaType"];
+    sourceSha256: string;
+    applicabilityNotes?: string;
+    sourceExemption?: string;
+    sources: CatalogKnowledgeSource[];
+  };
+}
+
+export type HostedKnowledgeResult = HostedCatalogResult | HostedWorkflowResult | HostedKnowledgeSearchResult | HostedKnowledgeGetResult;
+
+export interface KnowledgeService {
+  readonly metadata: HostedKnowledgeMetadata;
+  catalog(input: unknown): HostedCatalogResult;
+  workflow(input: unknown): HostedWorkflowResult;
+  search(input: unknown): HostedKnowledgeSearchResult;
+  get(input: unknown): HostedKnowledgeGetResult;
+}

package/kernel/lib/atomic-file.ts

@@ -0,0 +1,34 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+export function atomicFile(file: string, bytes: string): void {
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    const descriptor = openSync(temporary, "wx", 0o600);
+    try {
+      writeFileSync(descriptor, bytes);
+      fsyncSync(descriptor);
+    } finally {
+      closeSync(descriptor);
+    }
+    renameSync(temporary, file);
+    const directory = openSync(path.dirname(file), "r");
+    try {
+      fsyncSync(directory);
+    } finally {
+      closeSync(directory);
+    }
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+export function durableUnlink(file: string): void {
+  unlinkSync(file);
+  const descriptor = openSync(path.dirname(file), "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}

package/kernel/lib/bounded-file.ts

@@ -0,0 +1,24 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+
+/** Read bounded regular bytes without waiting on FIFOs or following a substituted final symlink. Callers validate ancestor containment. */
+export function boundedFileBytes(file: string, maxBytes: number): Buffer {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new Error("file.invalid_read_limit");
+  const before = lstatSync(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) throw new Error("file.nonregular_or_oversized");
+  const descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino || stat.size > maxBytes) throw new Error("file.changed_or_oversized");
+    const bytes = Buffer.alloc(maxBytes + 1);
+    let count = 0;
+    while (count < bytes.length) {
+      const received = readSync(descriptor, bytes, count, bytes.length - count, null);
+      if (!received) break;
+      count += received;
+    }
+    if (count > maxBytes) throw new Error("file.oversized");
+    return bytes.subarray(0, count);
+  } finally {
+    closeSync(descriptor);
+  }
+}

package/kernel/lib/cli.ts

@@ -0,0 +1,44 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Minimal `--flag value` / `--flag` (boolean) CLI argument parser shared by core's CLI
+ * entrypoints (reducer, session runner, onboarding, approve, migrate-v1). A flag followed by
+ * another `--flag` token, or by nothing, is recorded as `"true"`.
+ */
+export function parseArgs(argv: string[]): Record<string, string> {
+  const args: Record<string, string> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token?.startsWith("--")) {
+      const key = token.slice(2);
+      const next = argv[index + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        args[key] = next;
+        index += 1;
+      } else {
+        args[key] = "true";
+      }
+    }
+  }
+  return args;
+}
+
+/**
+ * True when the calling module was invoked directly as the process entrypoint (`tsx foo.ts`),
+ * not imported by another module. Pass the caller's own `import.meta.url` — this cannot read it
+ * itself, since that would report whether *this* module is the entrypoint instead.
+ */
+export function isMainModule(moduleUrl: string): boolean {
+  return process.argv[1] !== undefined && moduleUrl === pathToFileURL(process.argv[1]).href;
+}
+
+/**
+ * Resolve a user-supplied path against the directory the user typed it in. The packaged bin
+ * spawns every CLI with cwd at the package root (relative reads inside the CLIs depend on that)
+ * and passes the invoking shell's directory as B2C_APP_BUILDER_CALLER_CWD — without this, a consumer's
+ * `--workspace ./my-app` would silently resolve inside the engine package.
+ */
+export function resolveCallerPath(input: string): string {
+  return path.resolve(process.env.B2C_APP_BUILDER_CALLER_CWD?.trim() || process.cwd(), input);
+}

package/kernel/lib/empty-equivalent-evidence.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared scalar normalization for evidence cells.
+ *
+ * Founder Waiver and taste-gate fields must not treat decorated
+ * or spaced empty tokens as authored reasons. Keep the match on the whole
+ * cell after decoration strip, not on a substring of a real sentence.
+ */
+
+const EMPTY_EQUIVALENT = /^(?:none|n\/a|n a|na|not applicable|unknown|no reason)$/iu;
+
+export function normalizeEvidenceScalar(value: string): string {
+  let text = value;
+  for (let pass = 0; pass < 3; pass += 1) {
+    text = text.replace(/`([^`\r\n]*)`/gu, "$1");
+    text = text.replace(/\*\*([^*\r\n]*)\*\*/gu, "$1");
+    text = text.replace(/__([^_\r\n]*)__/gu, "$1");
+    text = text.replace(/(?<!\*)\*([^*\r\n]+)\*(?!\*)/gu, "$1");
+    text = text.replace(/(?<!_)_([^_\r\n]+)_(?!_)/gu, "$1");
+    text = text.replace(/~~([^~\r\n]+)~~/gu, "$1");
+  }
+  return text
+    .replace(/[\u2018\u2019\u201C\u201D"'`]/gu, "")
+    .replace(/[.:;!?()[\]{}]/gu, " ")
+    .replace(/[—–-]+/gu, " ")
+    .replace(/\s*\/\s*/gu, "/")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .toLocaleLowerCase("en-US");
+}
+
+export function isEmptyEquivalentEvidenceValue(value: string): boolean {
+  const normalized = normalizeEvidenceScalar(value);
+  if (normalized.length === 0) return true;
+  return EMPTY_EQUIVALENT.test(normalized);
+}

package/kernel/lib/later-guidance.ts

@@ -0,0 +1,128 @@
+/**
+ * Later-horizon is relative to the current workflow, not a global `loadWhen`
+ * phrase and not domain equality. A book this workflow binds as current work
+ * stays current even when it lives in another domain. The same book is later
+ * when a program packet binds it ahead of that work.
+ *
+ * Operator and security procedures (`paid-tool-routing`, secrets, Doppler,
+ * founder-zero-operator, security-release-hardening) stay current only on the
+ * action that owns them. Phrases such as `always` or `at workflow start` do
+ * not keep those books current on a program packet.
+ *
+ * Explicit later phrasing (`later, after launch`) still defers.
+ */
+const EXPLICIT_LATER = /\b(later|after (this|dispatch|launch|acceptance)|once .{0,80}complete|future)\b/i;
+const PROGRAM_FOREIGN_HORIZON =
+  /\b(before production|independent review|user-facing surface|native mobile screen|third-party skill pack|moving from planning|dispatching or coordinating subagents|launch readiness|store submission|public beta)\b/i;
+
+export interface LaterGuidanceContext {
+  workflowId?: string;
+  domainId?: string;
+}
+
+export interface LaterGuidanceEntry {
+  loadWhen: string;
+  path?: string;
+  title?: string;
+  referenceId?: string;
+  domainId?: string;
+}
+
+export function domainIdFromWorkflowId(workflowId: string): string | undefined {
+  const match = /^workflow\.([a-z0-9-]+)\./u.exec(workflowId);
+  return match ? `domain.${match[1]}` : undefined;
+}
+
+export function domainIdFromKnowledgePath(path: string): string | undefined {
+  const match = /(?:^|\/)knowledge\/([a-z0-9-]+)\//u.exec(path);
+  return match ? `domain.${match[1]}` : undefined;
+}
+
+export function laterGuidanceContext(workflowId: string, domainId?: string): LaterGuidanceContext {
+  return { workflowId, domainId: domainId ?? domainIdFromWorkflowId(workflowId) };
+}
+
+function workflowDomain(context: LaterGuidanceContext): string | undefined {
+  return context.domainId ?? (context.workflowId ? domainIdFromWorkflowId(context.workflowId) : undefined);
+}
+
+function entryDomain(entry: Omit<LaterGuidanceEntry, "loadWhen">): string | undefined {
+  return entry.domainId ?? (entry.path ? domainIdFromKnowledgePath(entry.path) : undefined);
+}
+
+export function isProgramPacket(context: LaterGuidanceContext = {}): boolean {
+  const workflowId = context.workflowId ?? "";
+  return workflowDomain(context) === "domain.orchestration" || /full-launch-program/i.test(workflowId);
+}
+
+function workflowBookTail(workflowId: string): string | undefined {
+  return /^workflow\.[a-z0-9-]+\.(.+)$/u.exec(workflowId)?.[1];
+}
+
+function isExactWorkflowBook(entry: Omit<LaterGuidanceEntry, "loadWhen">, context: LaterGuidanceContext): boolean {
+  const workflowId = context.workflowId?.trim();
+  if (!workflowId) return false;
+  const workflowLeaf = workflowId.replace(/^workflow\./u, "");
+  if (entry.referenceId) {
+    const referenceLeaf = entry.referenceId.replace(/^reference\./u, "");
+    if (workflowLeaf && referenceLeaf === workflowLeaf) return true;
+  }
+  const tail = workflowBookTail(workflowId);
+  if (!tail) return false;
+  const basename = entry.path?.split("/").pop()?.replace(/\.[^.]+$/u, "");
+  return basename === tail;
+}
+
+function workflowIdMentioned(loadWhen: string, workflowId: string | undefined): boolean {
+  return Boolean(workflowId && loadWhen.toLowerCase().includes(workflowId.toLowerCase()));
+}
+
+/**
+ * A book this workflow binds as current work. Domain equality is not enough:
+ * experience, store, and growth specialists bind design craft as current.
+ * Program packets only keep their own-role books.
+ */
+export function isWorkflowOwnBook(entry: Omit<LaterGuidanceEntry, "loadWhen">, context: LaterGuidanceContext = {}): boolean {
+  if (isExactWorkflowBook(entry, context)) return true;
+  if (!isProgramPacket(context)) return true;
+  const roleDomain = workflowDomain(context);
+  const bookDomain = entryDomain(entry);
+  return Boolean(roleDomain && bookDomain && roleDomain === bookDomain);
+}
+
+export function isLaterGuidance(
+  loadWhen: string,
+  context: LaterGuidanceContext = {},
+  entry: Omit<LaterGuidanceEntry, "loadWhen"> = {},
+): boolean {
+  const text = loadWhen.trim();
+  if (!text) return false;
+  if (workflowIdMentioned(text, context.workflowId)) return false;
+  if (isExactWorkflowBook(entry, context)) return false;
+  if (EXPLICIT_LATER.test(text)) return true;
+  if (isWorkflowOwnBook(entry, context)) return false;
+  return isProgramPacket(context) || PROGRAM_FOREIGN_HORIZON.test(text);
+}
+
+export function partitionLoadWhen<T extends LaterGuidanceEntry>(
+  entries: readonly T[],
+  context: LaterGuidanceContext = {},
+): { current: T[]; later: T[] } {
+  const current: T[] = [];
+  const later: T[] = [];
+  for (const entry of entries) {
+    (isLaterGuidance(entry.loadWhen, context, entry) ? later : current).push(entry);
+  }
+  return { current, later };
+}
+
+/** Prefer compose/dispatch deferred refs; otherwise partition the remaining load list. */
+export function classifiedBriefLoads<T extends LaterGuidanceEntry>(
+  load: readonly T[],
+  context: LaterGuidanceContext,
+  deferredLoad?: readonly T[],
+): { current: T[]; later: T[] } {
+  const partitioned = partitionLoadWhen(load, context);
+  if (deferredLoad && deferredLoad.length > 0) return { current: partitioned.current, later: [...deferredLoad] };
+  return partitioned;
+}