@warpgogol/werkstatt-shared 0.2.0

package/src/surface/geo.ts

@@ -0,0 +1,170 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0195] Dual SEO + GEO projection for the Programmatic Surface. Renders a baked page into a
+  clean Markdown twin (the AI-readable artifact, RFC-0184) and decides per-entry GEO inclusion.
+  The same dataset × axes that target Google long-tail also feed generative answer engines, with
+  no separate authoring. Suppressed (noindex / non-live) pages are excluded by the caller. Pure.
+</purpose>
+<non-goals>
+  <item>Do not write files or read the network (the kernel command does I/O).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0195: initial GEO projection.</item>
+  <item>Architecture review 2026-07-10: extract blockTwinRegistry so each block type has a registered twin renderer instead of pattern-matching on prop shapes in renderTwin.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { PageEntry } from "./types.ts";
+import type { VirtualRouteEntry } from "./types.ts";
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+/** A twin renderer for one block type: takes the block's props and returns Markdown lines. */
+export type BlockTwinRenderer = (props: Record<string, unknown>) => string[];
+
+const heroTwinRenderer: BlockTwinRenderer = (props) => {
+  const header = props.header as Record<string, unknown> | undefined;
+  const heading = str(props.heading) ?? str(header?.heading);
+  const lead = str(props.lead) ?? str(props.description) ?? str(props.tagline);
+  const lines: string[] = [];
+  if (heading) lines.push(`## ${heading}`);
+  if (lead) lines.push("", lead);
+  return lines;
+};
+
+const markdownTwinRenderer: BlockTwinRenderer = (props) => {
+  const heading = str(props.heading);
+  const lead = str(props.lead) ?? str(props.description) ?? str(props.tagline);
+  const lines: string[] = [];
+  if (heading) lines.push(`## ${heading}`);
+  if (lead) lines.push("", lead);
+  return lines;
+};
+
+const cardGridTwinRenderer: BlockTwinRenderer = (props) => {
+  const heading = str(props.heading);
+  const cards = (props.body as { cards?: Array<Record<string, unknown>> } | undefined)?.cards;
+  const lines: string[] = [];
+  if (heading) lines.push(`## ${heading}`);
+  for (const card of cards ?? []) {
+    const title = str(card.title);
+    const description = str(card.description);
+    if (title || description) {
+      lines.push(
+        "",
+        title ? `- **${title}**${description ? `: ${description}` : ""}` : `- ${description}`,
+      );
+    }
+  }
+  return lines;
+};
+
+const linkedCardGridTwinRenderer: BlockTwinRenderer = (props) => {
+  const heading = str(props.heading);
+  const cards =
+    (props.cards as Array<Record<string, unknown>> | undefined) ??
+    (props.body as { cards?: Array<Record<string, unknown>> } | undefined)?.cards;
+  const lines: string[] = [];
+  if (heading) lines.push(`## ${heading}`);
+  for (const card of cards ?? []) {
+    const title = str(card.title);
+    const description = str(card.description);
+    if (title || description) {
+      lines.push(
+        "",
+        title ? `- **${title}**${description ? `: ${description}` : ""}` : `- ${description}`,
+      );
+    }
+  }
+  return lines;
+};
+
+const listCardsTwinRenderer: BlockTwinRenderer = (props) => {
+  const heading = str(props.heading);
+  const items =
+    (props.items as Array<Record<string, unknown>> | undefined) ??
+    (props.body as { items?: Array<Record<string, unknown>> } | undefined)?.items;
+  const lines: string[] = [];
+  if (heading) lines.push(`## ${heading}`);
+  for (const item of items ?? []) {
+    const title = str(item.title);
+    const description = str(item.description) ?? str(item.body);
+    if (title || description) {
+      lines.push(
+        "",
+        title ? `- **${title}**${description ? `: ${description}` : ""}` : `- ${description}`,
+      );
+    }
+  }
+  return lines;
+};
+
+const ctaTwinRenderer: BlockTwinRenderer = (props) => {
+  const heading = str(props.heading);
+  const lines: string[] = [];
+  if (heading) lines.push(`## ${heading}`);
+  return lines;
+};
+
+const blockTwinRegistry: Readonly<Record<string, BlockTwinRenderer>> = {
+  hero: heroTwinRenderer,
+  markdown: markdownTwinRenderer,
+  "card-grid": cardGridTwinRenderer,
+  "linked-card-grid": linkedCardGridTwinRenderer,
+  "list-cards": listCardsTwinRenderer,
+  cta: ctaTwinRenderer,
+};
+
+/** Fallback: extract any visible string-valued props as bullet lines. */
+function fallbackTwinRenderer(props: Record<string, unknown>): string[] {
+  const lines: string[] = [];
+  const heading = str(props.heading);
+  if (heading) lines.push(`## ${heading}`);
+  const lead = str(props.lead) ?? str(props.description);
+  if (lead) lines.push("", lead);
+  return lines;
+}
+
+/**
+ * Render a baked page into a Markdown twin. Each block type has a registered twin renderer in
+ * {@link blockTwinRegistry}; unknown block types fall back to a generic visible-text extractor so
+ * they are never silently dropped. New block types register a renderer instead of patching this
+ * function.
+ */
+export function renderTwin(page: PageEntry, pathname: string): string {
+  const lines: string[] = [];
+  lines.push(`# ${page.title}`);
+  lines.push("");
+  if (page.description) {
+    lines.push(page.description);
+    lines.push("");
+  }
+  lines.push(`Source: ${pathname}`);
+  lines.push("");
+  for (const block of page.blocks) {
+    const props = (block.props ?? {}) as Record<string, unknown>;
+    const renderer = blockTwinRegistry[block.type ?? ""] ?? fallbackTwinRenderer;
+    const blockLines = renderer(props);
+    if (blockLines.length > 0) {
+      lines.push(...blockLines);
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+
+/** A live, non-suppressed entry whose GEO depth is full or twin-only gets a Markdown twin. */
+export function includeInTwins(entry: VirtualRouteEntry): boolean {
+  if (!entry.indexable || entry.noindex || !entry.page) return false;
+  return entry.geo !== "off";
+}
+
+/** A live, non-suppressed entry whose GEO depth is full contributes to llms.txt. */
+export function includeInLlms(entry: VirtualRouteEntry): boolean {
+  if (!entry.indexable || entry.noindex) return false;
+  return entry.geo === "full";
+}

package/src/surface/governance.ts

@@ -0,0 +1,146 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0278/RFC-0279/RFC-0285 shared governance contracts for PSEO autonomy,
+  auditable AI review, and human escalation budgets.
+</purpose>
+<non-goals>
+  <item>Do not run reviewers, mutate logs, or decide promotions.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0278/RFC-0279/RFC-0285: governance contract types.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const approverSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("human"), handle: z.string().min(1) }).strict(),
+  z
+    .object({
+      kind: z.literal("agent"),
+      modelId: z.string().min(1),
+      promptId: z.string().min(1),
+      version: z.string().min(1),
+    })
+    .strict(),
+]);
+
+export const fieldClassSchema = z.enum(["structural", "narrative", "claims", "product"]);
+export const autonomyLevelSchema = z.enum(["L0", "L1", "L2", "L3", "L4"]);
+
+export const autonomyScopeSchema = z
+  .object({
+    module: z.string().min(1),
+    fieldClass: fieldClassSchema,
+    locale: z.string().min(1),
+  })
+  .strict();
+
+export const autonomyStateSchema = z
+  .object({
+    scope: autonomyScopeSchema,
+    level: autonomyLevelSchema,
+    ceiling: autonomyLevelSchema,
+    sinceAt: z.string().datetime({ offset: true }),
+    evidenceRef: z.string().min(1),
+    lastReviewedBy: approverSchema.optional(),
+  })
+  .strict();
+
+export const approvalRecordSchema = z
+  .object({
+    approver: approverSchema,
+    atLevel: autonomyLevelSchema,
+    approvedAt: z.string().datetime({ offset: true }),
+    confidence: z.number().min(0).max(1).optional(),
+  })
+  .strict();
+
+export const reviewInputSchema = z
+  .object({
+    artifactRef: z.string().min(1),
+    fieldClass: fieldClassSchema,
+    grounding: z
+      .object({
+        record: z.unknown().optional(),
+        approvedClaims: z.array(z.unknown()).optional(),
+        moduleContext: z.unknown(),
+        glossaryId: z.string().min(1).optional(),
+        sourceArtifactRef: z.string().min(1).optional(),
+        translatorNoteId: z.string().min(1).optional(),
+      })
+      .strict(),
+  })
+  .strict();
+
+export const reviewVerdictSchema = z
+  .object({
+    artifactRef: z.string().min(1),
+    reviewer: z.object({ modelId: z.string(), promptId: z.string(), version: z.string() }).strict(),
+    decision: z.enum(["approve", "reject", "escalate"]),
+    confidence: z.number().min(0).max(1),
+    checks: z.array(
+      z.object({ id: z.string().min(1), pass: z.boolean(), note: z.string().optional() }).strict(),
+    ),
+    groundingViolations: z.array(z.string()),
+    samples: z.number().int().min(1),
+    reviewedAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+
+export const escalationReasonSchema = z.enum([
+  "low-reviewer-confidence",
+  "novel-template",
+  "claims-class",
+  "anomaly",
+  "demotion-review",
+  "product-language",
+]);
+
+export const escalationSchema = z
+  .object({
+    id: z.string().min(1),
+    scope: z.string().min(1),
+    reason: escalationReasonSchema,
+    artifactRef: z.string().min(1).optional(),
+    openedAt: z.string().datetime({ offset: true }),
+    resolvedAt: z.string().datetime({ offset: true }).optional(),
+    resolvedBy: z
+      .object({ kind: z.literal("human"), handle: z.string().min(1) })
+      .strict()
+      .optional(),
+    verdict: z.enum(["approve", "reject", "fix-record"]).optional(),
+    minutesSpent: z.number().min(0).optional(),
+    feedback: z
+      .object({
+        toGolden: z.boolean().optional(),
+        toCalibration: z.boolean().optional(),
+        toRecord: z.string().min(1).optional(),
+      })
+      .strict(),
+  })
+  .strict();
+
+export const escalationBudgetSchema = z
+  .object({
+    scope: z.string().min(1),
+    windowDays: z.number().int().min(1),
+    humanMinutesAvailable: z.number().min(0),
+    humanMinutesUsed: z.number().min(0),
+    minutesPer1000Pages: z.number().min(0),
+  })
+  .strict();
+
+export type Approver = z.infer<typeof approverSchema>;
+export type FieldClass = z.infer<typeof fieldClassSchema>;
+export type AutonomyLevel = z.infer<typeof autonomyLevelSchema>;
+export type AutonomyScope = z.infer<typeof autonomyScopeSchema>;
+export type AutonomyState = z.infer<typeof autonomyStateSchema>;
+export type ApprovalRecord = z.infer<typeof approvalRecordSchema>;
+export type ReviewInput = z.infer<typeof reviewInputSchema>;
+export type ReviewVerdict = z.infer<typeof reviewVerdictSchema>;
+export type EscalationReason = z.infer<typeof escalationReasonSchema>;
+export type Escalation = z.infer<typeof escalationSchema>;
+export type EscalationBudget = z.infer<typeof escalationBudgetSchema>;

package/src/surface/index.ts

@@ -0,0 +1,216 @@
+/*
+<MODULE_CONTRACT>
+<purpose>[RFC-0192] Public entrypoint for @warpgogol/werkstatt-shared/surface — the Programmatic Surface port.</purpose>
+<non-goals>
+  <item>Do not perform I/O — consumers (kernel command) supply loaded data.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0192: initial barrel.</item>
+  <item>RFC-0271: export SurfaceModuleContext schema, type, and ownership helpers.</item>
+  <item>RFC-0276: export Bordbuch event/status schemas and types.</item>
+  <item>RFC-0280/RFC-0281: export DemandSignal and WerkRecord schemas.</item>
+  <item>RFC-0278/RFC-0279/RFC-0285: export governance schemas and types.</item>
+  <item>RFC-0282/RFC-0283: export visibility and breaker schemas.</item>
+  <item>RFC-0284: export fleet Leitstand schemas and types.</item>
+  <item>RFC-0264 cleanup: root barrel delegates governance exports to the governance subpath.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type {
+  AxisTuple,
+  EligibilityPolicy,
+  IndexDecision,
+  IndexReason,
+  IndustryDossierFields,
+  LocalizedSlug,
+  LocalizedUniverse,
+  PageEntry,
+  PageSurfaceProvider,
+  RedirectPolicy,
+  SurfaceArtifact,
+  SurfaceAxis,
+  SurfaceBlock,
+  SurfaceCounts,
+  SurfaceManifest,
+  SurfaceNarrative,
+  SurfaceRecord,
+  SurfaceRecordImage,
+  VirtualRouteEntry,
+} from "./types.ts";
+
+export {
+  buildEligibilityMatrix,
+  countMatching,
+  enumerateCandidateTuples,
+  liveChildrenOf,
+  liveSiblingsOf,
+  matchesRecord,
+  nearestLiveAncestor,
+  normalizeSegment,
+  pathKey,
+  type AxisFieldMap,
+  type EligibilityMatrix,
+  type MatrixEntry,
+} from "./eligibility.ts";
+
+export {
+  assembleEntries,
+  buildAxes,
+  buildAxisFieldMap,
+  generateEntries,
+  pageIdFor,
+  resolvePolicy,
+  resolveSlug,
+  type Blueprint,
+  type BlueprintAxis,
+  type BlueprintDemandDepthPolicy,
+  type BlueprintDossier,
+  type BlueprintDuplicatePolicy,
+  type BlueprintEvidenceDepthPolicy,
+  type BlueprintIntersectionConfig,
+  type BlueprintLevel,
+  type BlueprintLinking,
+  type BlueprintPillar,
+  type BlueprintPillarAdaptation,
+  type BlueprintPillarAdaptationDimension,
+  type BlueprintPillarFinalCta,
+  type BlueprintPillarHero,
+  type BlueprintPillarProductPrice,
+  type BlueprintPolicy,
+  type BlueprintProjection,
+  type EnrichedFieldSpec,
+  type GeoDepth,
+  type IndustryPublicationGate,
+  type IntersectionGate,
+  type IntersectionSimilarity,
+  type LocalizedString,
+} from "./blueprint.ts";
+
+export { blueprintSchema, parseBlueprint, type ParseBlueprintResult } from "./blueprint-schema.ts";
+
+// Governance and operational schema bags (RFC-0271..0285) — explicit re-exports.
+export type {
+  BlueprintModuleClaim,
+  PseoStage,
+  SurfaceModuleContext,
+  SurfaceModules,
+  UrlPolicy,
+} from "./module-context.ts";
+export {
+  findDuplicateBlueprintClaims,
+  findModuleForBlueprint,
+  moduleReviewPolicySchema,
+  moduleSiteModeSchema,
+  normalizeSurfaceModules,
+  pseoStageSchema,
+  surfaceModuleContextSchema,
+  surfaceModulesSchema,
+  urlPolicySchema,
+} from "./module-context.ts";
+
+export type {
+  DemandAxes,
+  DemandIntent,
+  DemandSignal,
+  DemandSignalSource,
+  WerkRecord,
+} from "./evidence-records.ts";
+export {
+  demandAxesSchema,
+  demandIntentSchema,
+  demandSignalSchema,
+  demandSignalSourceSchema,
+  werkRecordSchema,
+} from "./evidence-records.ts";
+
+export type {
+  ApprovalRecord,
+  Approver,
+  AutonomyLevel,
+  AutonomyScope,
+  AutonomyState,
+  Escalation,
+  EscalationBudget,
+  EscalationReason,
+  FieldClass,
+  ReviewInput,
+  ReviewVerdict,
+} from "./governance.ts";
+export {
+  approvalRecordSchema,
+  approverSchema,
+  autonomyLevelSchema,
+  autonomyScopeSchema,
+  autonomyStateSchema,
+  escalationBudgetSchema,
+  escalationReasonSchema,
+  escalationSchema,
+  fieldClassSchema,
+  reviewInputSchema,
+  reviewVerdictSchema,
+} from "./governance.ts";
+
+export type {
+  ClusterAction,
+  ClusterOutcome,
+  VisibilitySnapshot,
+  VisibilitySource,
+} from "./visibility.ts";
+export {
+  clusterActionSchema,
+  clusterOutcomeSchema,
+  visibilitySnapshotSchema,
+  visibilitySourceSchema,
+} from "./visibility.ts";
+
+export type {
+  BreakerVerdict,
+  SurfaceState,
+  SurfaceStateStatus,
+  Tripwire,
+  TripwireAction,
+} from "./breaker.ts";
+export {
+  breakerVerdictSchema,
+  surfaceStateSchema,
+  surfaceStateStatusSchema,
+  tripwireActionSchema,
+  tripwireSchema,
+} from "./breaker.ts";
+
+export type {
+  FleetBreakerState,
+  FleetJob,
+  FleetJobKind,
+  FleetPlan,
+  FleetSiteStatus,
+} from "./fleet.ts";
+export {
+  fleetBreakerStateSchema,
+  fleetJobKindSchema,
+  fleetJobSchema,
+  fleetPlanSchema,
+  fleetSiteStatusSchema,
+} from "./fleet.ts";
+
+export {
+  buildTokenDocFreq,
+  pageText,
+  scoreSubstance,
+  tokenize,
+  type SubstanceComponents,
+  type SubstanceScore,
+} from "./substance.ts";
+
+export { includeInLlms, includeInTwins, renderTwin, type BlockTwinRenderer } from "./geo.ts";
+
+export {
+  composeIndexDecision,
+  evaluateBudgetGate,
+  evaluateDemandGate,
+  evaluateEvidenceGate,
+  evaluateFreshnessGate,
+  evaluateSubstanceGate,
+  type GateResult,
+} from "./decision-composer.ts";

package/src/surface/io/index.ts

@@ -0,0 +1,18 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0473: Barrel for @warpgogol/werkstatt-shared/surface/io — I/O helpers extracted from site-kernel-checks.</purpose>
+<non-goals>
+  <item>Does not contain pure domain logic — that lives in the root @warpgogol/werkstatt-shared/surface entry points.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0473: initial io barrel for cross-package I/O helpers.</item>
+</CHANGE_SUMMARY>
+*/
+
+export {
+  loadSurfaceModuleContexts,
+  type LoadedModuleContexts,
+} from "./surface-module-context-io.ts";
+
+export { readVisibilityOutcomes, type OutcomesPayload } from "./visibility-outcomes-io.ts";

package/src/surface/io/surface-module-context-io.ts

@@ -0,0 +1,60 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0473: I/O helper for loading Programmatic Surface module contexts from a Sternsystem's
+  system.md. Extracted from site-kernel-checks so bordbuch.generate in site-kernel-handoff
+  can read PSEO module context without depending on site-kernel-checks.
+</purpose>
+<non-goals>
+  <item>Do not mutate system.md.</item>
+  <item>Do not make LLM calls or interpret Blueprint axis policy.</item>
+  <item>Do not define validation diagnostics — that lives in site-kernel-checks.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0473: extract loadSurfaceModuleContexts from site-kernel-checks for cross-package reuse.</item>
+  <item>RFC-0868: inline loadSystemManifest to break dependency on werkstatt-site/content.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { join } from "node:path";
+import { readFile, access } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { normalizeSurfaceModules, type SurfaceModules } from "../index.ts";
+
+async function loadSystemManifestRaw(contentDirectory: string): Promise<Record<string, unknown>> {
+  const systemMdPath = join(contentDirectory, "system.md");
+  await access(systemMdPath);
+  const content = await readFile(systemMdPath, "utf8");
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return {};
+  return parseYaml(match[1]) as Record<string, unknown>;
+}
+
+export interface LoadedModuleContexts {
+  modules: SurfaceModules;
+  declaredBlueprints: string[];
+  supportedLocales: string[];
+  defaultLocale?: string;
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.map(String).filter(Boolean) : [];
+}
+
+export async function loadSurfaceModuleContexts(appDir: string): Promise<LoadedModuleContexts> {
+  const record = await loadSystemManifestRaw(join(appDir, "src", "content"));
+  const i18n = record.i18n as { default?: string; supported?: Record<string, unknown> } | undefined;
+  const surface = record.surface as { blueprints?: unknown; modules?: unknown } | undefined;
+  const supportedLocales = i18n?.supported
+    ? Object.keys(i18n.supported)
+    : i18n?.default
+      ? [i18n.default]
+      : [];
+  return {
+    modules: normalizeSurfaceModules(surface?.modules ?? {}),
+    declaredBlueprints: asStringArray(surface?.blueprints),
+    supportedLocales,
+    defaultLocale: i18n?.default,
+  };
+}

package/src/surface/io/visibility-outcomes-io.ts

@@ -0,0 +1,46 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0473: I/O helper for reading PSEO visibility outcomes from a Sternsystem's
+  generated outcomes file. Extracted from site-kernel-checks so bordbuch.generate
+  in site-kernel-handoff can read visibility outcomes without depending on site-kernel-checks.
+</purpose>
+<non-goals>
+  <item>Do not write outcomes — that lives in site-kernel-checks visibility commands.</item>
+  <item>Do not interpret outcomes or propose cluster actions.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0473: extract readVisibilityOutcomes from site-kernel-checks for cross-package reuse.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as yamlParse } from "yaml";
+import type { ClusterOutcome } from "../visibility.ts";
+
+export interface OutcomesPayload {
+  generatedAt: string | null;
+  policy: {
+    observationWindowDays: number;
+    expand: { indexationRateMin: number; medianImpressionsMin: number };
+    prune: { afterWindows: number; impressionsMax: number };
+    enrich: { requirePositiveDemand: boolean };
+  };
+  outcomes: ClusterOutcome[];
+  demandCorrections: Array<{
+    clusterId: string;
+    realizedImpressions: number;
+    demandVolume: number;
+  }>;
+}
+
+const OUTCOMES_FILE = "src/surface/visibility/outcomes.generated.yaml";
+
+export async function readVisibilityOutcomes(appDir: string): Promise<OutcomesPayload | null> {
+  const path = join(appDir, OUTCOMES_FILE);
+  if (!existsSync(path)) return null;
+  return yamlParse(await readFile(path, "utf8")) as OutcomesPayload;
+}