@warpgogol/werkstatt-shared 0.2.0

package/src/surface/tests/eligibility.test.ts

@@ -0,0 +1,302 @@
+import { test, expect, describe } from "vitest";
+import {
+  normalizeSegment,
+  matchesRecord,
+  countMatching,
+  buildRecordIndex,
+  countMatchingIndexed,
+  pathKey,
+  enumerateCandidateTuples,
+  buildEligibilityMatrix,
+  nearestLiveAncestor,
+  liveChildrenOf,
+  liveSiblingsOf,
+  type AxisFieldMap,
+} from "../eligibility.ts";
+import type { SurfaceAxis, SurfaceRecord, EligibilityPolicy } from "../types.ts";
+
+const SEGMENT_PATTERN = /^[a-z0-9-]+$/;
+
+const defaultPolicy: EligibilityPolicy = {
+  minRecordsPerDepth: { 0: 1, 1: 1, 2: 1 },
+  noindexBelowPerDepth: {},
+  redirectPolicy: "nearest-ancestor",
+  trailingSlash: true,
+  segmentPattern: SEGMENT_PATTERN,
+};
+
+const axes: SurfaceAxis[] = [
+  { id: "trade", universe: ["elektriker", "friseur"] },
+  { id: "region", universe: ["berlin", "hamburg"] },
+];
+
+const axisFieldMap: AxisFieldMap = { trade: "trade", region: "region" };
+
+const records: SurfaceRecord[] = [
+  { trade: "elektriker", region: "berlin", status: "active" },
+  { trade: "elektriker", region: "hamburg", status: "active" },
+  { trade: "friseur", region: "berlin", status: "active" },
+  { trade: "friseur", region: "hamburg", status: "archived" },
+];
+
+describe("normalizeSegment", () => {
+  test("lowercases and converts underscores to dashes", () => {
+    expect(normalizeSegment("Hello_World", SEGMENT_PATTERN)).toBe("hello-world");
+  });
+
+  test("trims whitespace", () => {
+    expect(normalizeSegment("  berlin  ", SEGMENT_PATTERN)).toBe("berlin");
+  });
+
+  test("throws on invalid characters", () => {
+    expect(() => normalizeSegment("hello world!", SEGMENT_PATTERN)).toThrow();
+  });
+
+  test("passes through already-normalized segment", () => {
+    expect(normalizeSegment("elektriker", SEGMENT_PATTERN)).toBe("elektriker");
+  });
+});
+
+describe("matchesRecord", () => {
+  test("matches when all constrained axes match", () => {
+    expect(
+      matchesRecord(records[0]!, { trade: "elektriker", region: "berlin" }, axisFieldMap),
+    ).toBe(true);
+  });
+
+  test("does not match when one axis differs", () => {
+    expect(matchesRecord(records[0]!, { trade: "friseur", region: "berlin" }, axisFieldMap)).toBe(
+      false,
+    );
+  });
+
+  test("matches when tuple is empty (no constraints)", () => {
+    expect(matchesRecord(records[0]!, {}, axisFieldMap)).toBe(true);
+  });
+
+  test("matches when only one axis is constrained", () => {
+    expect(matchesRecord(records[0]!, { trade: "elektriker" }, axisFieldMap)).toBe(true);
+    expect(matchesRecord(records[0]!, { trade: "friseur" }, axisFieldMap)).toBe(false);
+  });
+
+  test("returns false when axis field is missing from map", () => {
+    expect(matchesRecord(records[0]!, { unknown: "x" }, axisFieldMap)).toBe(false);
+  });
+
+  test("matches array field values", () => {
+    const rec: SurfaceRecord = { tags: ["a", "b"], status: "active" };
+    expect(matchesRecord(rec, { tags: "a" }, { tags: "tags" })).toBe(true);
+    expect(matchesRecord(rec, { tags: "c" }, { tags: "tags" })).toBe(false);
+  });
+});
+
+describe("countMatching", () => {
+  test("counts all active records for empty tuple", () => {
+    expect(countMatching(records, {}, axisFieldMap)).toBe(3);
+  });
+
+  test("counts matching records for a specific tuple", () => {
+    expect(countMatching(records, { trade: "elektriker" }, axisFieldMap)).toBe(2);
+    expect(countMatching(records, { trade: "friseur" }, axisFieldMap)).toBe(1);
+  });
+
+  test("excludes archived records", () => {
+    expect(countMatching(records, { trade: "friseur", region: "hamburg" }, axisFieldMap)).toBe(0);
+  });
+});
+
+describe("buildRecordIndex + countMatchingIndexed", () => {
+  const index = buildRecordIndex(records, axisFieldMap);
+
+  test("index count matches linear count for empty tuple", () => {
+    expect(countMatchingIndexed({}, axisFieldMap, index)).toBe(3);
+  });
+
+  test("index count matches linear count for specific tuple", () => {
+    expect(countMatchingIndexed({ trade: "elektriker" }, axisFieldMap, index)).toBe(2);
+    expect(countMatchingIndexed({ trade: "friseur", region: "berlin" }, axisFieldMap, index)).toBe(
+      1,
+    );
+  });
+
+  test("returns 0 for non-existent axis", () => {
+    expect(countMatchingIndexed({ unknown: "x" }, axisFieldMap, index)).toBe(0);
+  });
+
+  test("returns 0 for non-existent value", () => {
+    expect(countMatchingIndexed({ trade: "nonexistent" }, axisFieldMap, index)).toBe(0);
+  });
+});
+
+describe("pathKey", () => {
+  test("depth 0 produces just '0'", () => {
+    expect(pathKey(0, {}, ["trade", "region"])).toBe("0");
+  });
+
+  test("depth 1 includes first axis value", () => {
+    expect(pathKey(1, { trade: "elektriker" }, ["trade", "region"])).toBe("1|elektriker");
+  });
+
+  test("depth 2 includes both axis values", () => {
+    expect(pathKey(2, { trade: "elektriker", region: "berlin" }, ["trade", "region"])).toBe(
+      "2|elektriker|berlin",
+    );
+  });
+
+  test("missing axis value becomes empty string", () => {
+    expect(pathKey(2, { trade: "elektriker" }, ["trade", "region"])).toBe("2|elektriker|");
+  });
+});
+
+describe("enumerateCandidateTuples", () => {
+  test("depth 0 yields single empty tuple", () => {
+    const tuples = [...enumerateCandidateTuples(axes, 0)];
+    expect(tuples).toEqual([{}]);
+  });
+
+  test("depth 1 yields all first-axis values", () => {
+    const tuples = [...enumerateCandidateTuples(axes, 1)];
+    expect(tuples).toHaveLength(2);
+    expect(tuples[0]).toEqual({ trade: "elektriker" });
+    expect(tuples[1]).toEqual({ trade: "friseur" });
+  });
+
+  test("depth 2 yields cartesian product", () => {
+    const tuples = [...enumerateCandidateTuples(axes, 2)];
+    expect(tuples).toHaveLength(4);
+    expect(tuples.map((t) => `${t.trade}/${t.region}`).sort()).toEqual([
+      "elektriker/berlin",
+      "elektriker/hamburg",
+      "friseur/berlin",
+      "friseur/hamburg",
+    ]);
+  });
+
+  test("empty universe yields nothing", () => {
+    const emptyAxes: SurfaceAxis[] = [{ id: "trade", universe: [] }];
+    expect([...enumerateCandidateTuples(emptyAxes, 1)]).toHaveLength(0);
+  });
+});
+
+describe("buildEligibilityMatrix", () => {
+  const matrix = buildEligibilityMatrix(axes, axisFieldMap, records, defaultPolicy);
+
+  test("has correct axis order", () => {
+    expect(matrix.axisOrder).toEqual(["trade", "region"]);
+  });
+
+  test("root entry (depth 0) is live with 3 records", () => {
+    const root = matrix.byKey.get("0");
+    expect(root).toBeDefined();
+    expect(root!.recordCount).toBe(3);
+    expect(root!.indexable).toBe(true);
+  });
+
+  test("elektriker depth 1 is live with 2 records", () => {
+    const entry = matrix.byKey.get("1|elektriker");
+    expect(entry).toBeDefined();
+    expect(entry!.recordCount).toBe(2);
+    expect(entry!.indexable).toBe(true);
+  });
+
+  test("friseur depth 1 is live with 1 record", () => {
+    const entry = matrix.byKey.get("1|friseur");
+    expect(entry).toBeDefined();
+    expect(entry!.recordCount).toBe(1);
+    expect(entry!.indexable).toBe(true);
+  });
+
+  test("friseur/hamburg depth 2 is not live (archived only)", () => {
+    const entry = matrix.byKey.get("2|friseur|hamburg");
+    expect(entry).toBeUndefined();
+  });
+
+  test("elektriker/berlin depth 2 is live", () => {
+    const entry = matrix.byKey.get("2|elektriker|berlin");
+    expect(entry).toBeDefined();
+    expect(entry!.indexable).toBe(true);
+  });
+
+  test("forceNonIndexableDepths gates a depth as regional-gated", () => {
+    const matrix2 = buildEligibilityMatrix(axes, axisFieldMap, records, defaultPolicy, {
+      forceNonIndexableDepths: [2],
+      maxStubDepth: 2,
+    });
+    const entry = matrix2.byKey.get("2|elektriker|berlin");
+    expect(entry).toBeDefined();
+    expect(entry!.indexable).toBe(false);
+    expect(entry!.decision.reason).toBe("regional-gated");
+  });
+});
+
+describe("nearestLiveAncestor", () => {
+  const matrix = buildEligibilityMatrix(axes, axisFieldMap, records, defaultPolicy);
+
+  test("returns root for depth 1 entry", () => {
+    const entry = matrix.byKey.get("1|elektriker")!;
+    const ancestor = nearestLiveAncestor(entry, matrix, defaultPolicy);
+    expect(ancestor?.depth).toBe(0);
+  });
+
+  test("returns nearest live ancestor for depth 2 entry", () => {
+    const entry = matrix.byKey.get("2|elektriker|berlin")!;
+    const ancestor = nearestLiveAncestor(entry, matrix, defaultPolicy);
+    expect(ancestor?.depth).toBe(1);
+    expect(ancestor?.tuple.trade).toBe("elektriker");
+  });
+
+  test("redirectPolicy root always returns root", () => {
+    const rootPolicy = { ...defaultPolicy, redirectPolicy: "root" as const };
+    const entry = matrix.byKey.get("2|elektriker|berlin")!;
+    const ancestor = nearestLiveAncestor(entry, matrix, rootPolicy);
+    expect(ancestor?.depth).toBe(0);
+  });
+});
+
+describe("liveChildrenOf", () => {
+  const matrix = buildEligibilityMatrix(axes, axisFieldMap, records, defaultPolicy);
+
+  test("root has live children at depth 1", () => {
+    const root = matrix.byKey.get("0")!;
+    const children = liveChildrenOf(root, matrix);
+    expect(children).toHaveLength(2);
+    expect(children.map((c) => c.tuple.trade).sort()).toEqual(["elektriker", "friseur"]);
+  });
+
+  test("elektriker depth 1 has live children at depth 2", () => {
+    const parent = matrix.byKey.get("1|elektriker")!;
+    const children = liveChildrenOf(parent, matrix);
+    expect(children).toHaveLength(2);
+    expect(children.map((c) => c.tuple.region).sort()).toEqual(["berlin", "hamburg"]);
+  });
+
+  test("friseur depth 1 has one live child (berlin)", () => {
+    const parent = matrix.byKey.get("1|friseur")!;
+    const children = liveChildrenOf(parent, matrix);
+    expect(children).toHaveLength(1);
+    expect(children[0]!.tuple.region).toBe("berlin");
+  });
+});
+
+describe("liveSiblingsOf", () => {
+  const matrix = buildEligibilityMatrix(axes, axisFieldMap, records, defaultPolicy);
+
+  test("depth 0 has no siblings", () => {
+    const root = matrix.byKey.get("0")!;
+    expect(liveSiblingsOf(root, matrix)).toHaveLength(0);
+  });
+
+  test("elektriker at depth 1 has friseur as sibling", () => {
+    const entry = matrix.byKey.get("1|elektriker")!;
+    const siblings = liveSiblingsOf(entry, matrix);
+    expect(siblings).toHaveLength(1);
+    expect(siblings[0]!.tuple.trade).toBe("friseur");
+  });
+
+  test("elektriker/berlin at depth 2 has elektriker/hamburg as sibling", () => {
+    const entry = matrix.byKey.get("2|elektriker|berlin")!;
+    const siblings = liveSiblingsOf(entry, matrix);
+    expect(siblings).toHaveLength(1);
+    expect(siblings[0]!.tuple.region).toBe("hamburg");
+  });
+});

package/src/surface/types.ts

@@ -0,0 +1,289 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0192] Closed contracts for the Programmatic Surface route-source port: the axis/record
+  model, the eligibility policy, the materialized virtual route entry, and the PageSurfaceProvider
+  interface. Framework-free — no Astro, no Node I/O. These types are the seam shared by the
+  build-time generator (kernel command) and the runtime registry merge.
+</purpose>
+<non-goals>
+  <item>Do not read content or the filesystem — all I/O lives in the kernel command wrapper.</item>
+  <item>Do not define the Blueprint schema (see blueprint.ts) or substance/budget/freshness (later RFCs).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0192: initial contracts.</item>
+  <item>RFC-0207: SurfaceNarrative (bespoke per-page hero/section prose) + SurfaceRecordImage (per-record image token + alt).</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * RFC-0207: the bespoke per-page narrative that replaces template-glued headings for an indexable
+ * page. Produced once per live tuple (or per record) by surface.enrich, stored frozen + approved as
+ * a content entry, and read by the baker. The h1/lead/tagline land in the hero; bridges become
+ * connective section prose between the field-driven blocks. Transcreated natively per language.
+ */
+export interface SurfaceNarrative {
+  /** Grammatically complete page H1 (not a token-glued title). */
+  h1: string;
+  /** Hero lead — distinct from any record field and from the tagline. */
+  lead: string;
+  /** Hero tagline — distinct from the lead. */
+  tagline?: string;
+  /** Connective section prose woven between the field-driven blocks. */
+  bridges?: Array<{ heading: string; body: string }>;
+}
+
+/**
+ * RFC-0207: a surface dataset record's image. `image` is a content-asset token resolved exactly like
+ * a hero `leadImage.src` / `portraitImage` (bare filename under the app's content assets, RFC-0167);
+ * `imageAlt` is the meaningful alt text (per-language record carries the per-language alt). Mixed into
+ * SurfaceRecord so the baker can read it without a separate load.
+ */
+export interface SurfaceRecordImage {
+  image?: string;
+  imageAlt?: string;
+}
+
+/**
+ * RFC-0192: a block in a baked page. Structurally compatible with `@warpgogol/werkstatt-shared/share` `BlockEntry`, but
+ * declared here so `@warpgogol/werkstatt-shared/surface` stays the lower-level package with no dependency on share
+ * (avoids a workspace cycle — share consumes surface's route types).
+ */
+export interface SurfaceBlock {
+  id?: string;
+  /** CMS-facing archetype slug (e.g. "hero", "markdown", "final-cta"). */
+  type?: string;
+  /** PlanetName/MoonName (normalized from `type` for internal resolution). */
+  use?: string;
+  props: Record<string, unknown>;
+  layer?: "shell" | "section";
+}
+
+/** RFC-0192: a baked block-declarative page. Structurally compatible with `@warpgogol/werkstatt-shared/share` `PageEntry`. */
+export interface PageEntry {
+  kind: "page";
+  cosmicStar: string;
+  title: string;
+  description: string;
+  lang: string;
+  blocks: SurfaceBlock[];
+}
+
+/** A single combinatorial axis and the closed universe of value slugs it ranges over. */
+export interface SurfaceAxis {
+  id: string;
+  /** Value slugs, sourced from a content-source collection by the generator. */
+  universe: readonly string[];
+}
+
+/** A partial assignment of axis ids → chosen value (undefined ⇒ axis not yet constrained). */
+export type AxisTuple = Record<string, string | undefined>;
+
+/**
+ * RFC-0199: a value's slug, optionally localized per language. The `neutral` slug is the
+ * language-neutral identity key (filename stem / `slug` field) and the fallback; `byLang`
+ * supplies a per-language URL segment. Languages absent from `byLang` fall back to `neutral`.
+ */
+export interface LocalizedSlug {
+  neutral: string;
+  byLang?: Record<string, string>;
+}
+
+/**
+ * RFC-0199: per-axis localized slug map — axisId → (neutral value slug → its LocalizedSlug).
+ * An empty/absent universe makes slug rendering fall back to the neutral tuple value, so the
+ * generator output is byte-identical to pre-RFC-0199 behavior when no localized slugs exist.
+ */
+export type LocalizedUniverse = Record<string, Map<string, LocalizedSlug>>;
+
+/**
+ * A dataset row projected into axis-addressable fields. Each axis declares which record field
+ * carries its membership (a value or an array of values). `status` gates live vs archived rows.
+ */
+export type SurfaceRecord = Record<string, string | string[] | undefined> & {
+  slug?: string;
+  status?: "active" | "archived";
+};
+
+export type RedirectPolicy = "nearest-ancestor" | "root";
+
+/**
+ * The eligibility policy: how many records a combination needs to go live at each depth, when a
+ * live page is demoted to noindex, what empty combinations redirect to, and URL-segment rules.
+ * Axis-generic generalization of the legacy foerderung policy.
+ */
+export interface EligibilityPolicy {
+  /** depth → minimum active records required to emit a live page. */
+  minRecordsPerDepth: Readonly<Record<number, number>>;
+  /** depth → live-but-`noindex` threshold (live page tagged noindex below this count). */
+  noindexBelowPerDepth: Readonly<Record<number, number>>;
+  redirectPolicy: RedirectPolicy;
+  trailingSlash: boolean;
+  /** Allowed URL-segment shape (single lowercase dash segment by default). */
+  segmentPattern: RegExp;
+}
+
+/**
+ * The reason a generated page is not indexable. Extended by later RFCs (substance/budget/freshness);
+ * RFC-0192 emits only the record-count reasons.
+ */
+export type IndexReason =
+  | "too-few-records"
+  | "thin" // RFC-0194
+  | "over-budget" // RFC-0196
+  | "decayed" // RFC-0196
+  | "regional-gated" // RFC-0240
+  | "invalid-freshness" // RFC-0274
+  | "missing-evidence" // RFC-0274
+  | "missing-demand" // RFC-0280
+  | "missing-werk-evidence" // RFC-0281
+  | "navigation-noindex" // RFC-0324
+  | "redirect-stub"
+  | "duplicate"; // RFC-0274
+
+/** The composed indexability decision for a generated page. Later RFCs fill the optional gates. */
+export interface IndexDecision {
+  recordGate: boolean;
+  substanceGate?: boolean;
+  evidenceGate?: boolean;
+  demandGate?: boolean;
+  duplicateGate?: boolean;
+  withinBudget?: boolean;
+  fresh?: boolean;
+  indexable: boolean;
+  noindex: boolean;
+  reason?: IndexReason;
+  /** RFC-0194: the page substance score (0..100) that informed the substance gate. */
+  substanceScore?: number;
+  /** RFC-0281: count of consented Werk records backing this tuple. */
+  werkEvidenceCount?: number;
+}
+
+/** One materialized generated route. The single unit the registry merge consumes. */
+export interface VirtualRouteEntry {
+  /** Owning Blueprint id (e.g. "website-local"). */
+  surfaceId: string;
+  /** Synthetic stable page id, e.g. "website-local:elektriker:berlin". */
+  pageId: string;
+  /** lang → localized slug. */
+  routes: Record<string, string>;
+  axes: AxisTuple;
+  depth: number;
+  recordCount: number;
+  indexable: boolean;
+  noindex: boolean;
+  /** For non-live (redirect-stub) entries: the live ancestor pageId to 301 to. */
+  redirectToPageId?: string;
+  /** For live noindex navigation pages: pageId whose URL should be rendered as canonical. */
+  canonicalPageId?: string;
+  /** Semantic page type for JSON-LD / OG meta (defaults to "content"). */
+  semanticType?: string;
+  /**
+   * RFC-0325: dated-editorial article metadata, present when `semanticType` is "article". Mirrors
+   * the system.md `pages[].article` shape exactly so the RFC-0317 update-stamp resolver
+   * (`resolveAuthoredStamp`) and the Astro render layer's Article/BlogPosting JSON-LD wiring work
+   * for a Programmatic Surface page without any source-specific branching.
+   */
+  article?: {
+    publishedAt: string;
+    updatedAt?: string;
+    author?: string;
+    tags?: string[];
+  };
+  /** RFC-0195: per-depth GEO contribution — "full" (llms.txt + twin), "twin-only", "off". */
+  geo?: "full" | "twin-only" | "off";
+  /**
+   * Optional page-level site-background image name (resolved via the app's content assets, same as
+   * an authored page's `shell.background` imageName in system.md). When set, the page handler renders
+   * a shell-layer background instead of the generic `home-bg` default. Omit for the default.
+   */
+  backgroundImage?: string;
+  /**
+   * RFC-0192: the resolved page. In "inline" bake mode it carries the full blocks. In "lazy" mode it
+   * carries only metadata (title/description, empty blocks) and the full page lives in its own file
+   * (`.surface-cache/<pageId>.yaml`), loaded on demand at render.
+   */
+  page?: PageEntry;
+  /**
+   * RFC-0193: per-language baked pages (multilingual surfaces). Keyed by lang. `page` mirrors the
+   * default-language entry here. Language-neutral consumers (substance, counts) use `page`; per-lang
+   * consumers (render, Markdown twins, llms.txt) use `pages[lang] ?? page`.
+   */
+  pages?: Record<string, PageEntry>;
+  /** RFC-0192: true when the full page blocks live in a per-page file (lazy bake). */
+  lazy?: boolean;
+  /**
+   * RFC-0207: non-default languages whose localized page was omitted because its baked content fell
+   * back to the default language (no native record fields and no approved narrative). Their `routes`
+   * + `pages` entries are dropped, so the de-fallback page never renders under a localized URL, is
+   * never indexed, and never enters the sitemap/hreflang/twins. surface.validate reports each as an
+   * `untranslated-route` error. Reversible: supply native content (or an approved narrative) and the
+   * route reappears on the next generate.
+   */
+  untranslatedLangs?: string[];
+  /** Decision provenance for the manifest (RFC-0194/0196 enrich this). */
+  decision?: IndexDecision;
+}
+
+/**
+ * The closed route-source port. One implementation per Blueprint (RFC-0193).
+ * `enumerate` runs at build time (Node); `resolve` may run at build time (baked) or render time.
+ */
+export interface PageSurfaceProvider {
+  readonly id: string;
+  enumerate(lang: string): Promise<VirtualRouteEntry[]>;
+  resolve(entry: VirtualRouteEntry, lang: string): Promise<PageEntry>;
+}
+
+/** Per-surface generation counts (written into pseo-manifest.json). */
+export interface SurfaceCounts {
+  surfaceId: string;
+  generated: number;
+  indexable: number;
+  noindex: number;
+  redirected: number;
+  /** RFC-0194: live pages suppressed by the substance gate. */
+  thin?: number;
+  /** RFC-0194: median Page Substance Score across live pages. */
+  medianSubstance?: number;
+  /** RFC-0324: legacy composite score retained for diagnostics while medianSubstance is unique-share. */
+  legacyMedianSubstanceScore?: number;
+  /** RFC-0324: distribution of unique token share across non-redirect generated pages. */
+  uniqueTokenShareBands?: {
+    lt030: number;
+    gte030lt050: number;
+    gte050: number;
+  };
+  /** RFC-0195: Markdown twins emitted (GEO corpus). */
+  twins?: number;
+  /** RFC-0195: pages contributing to llms.txt (GEO depth "full"). */
+  inLlms?: number;
+}
+
+/** The pseo-manifest.json payload. */
+export interface SurfaceManifest {
+  generatedAt: string | null;
+  surfaces: SurfaceCounts[];
+}
+
+/** The src/surface.generated.yaml payload consumed by the runtime registry merge. */
+export interface SurfaceArtifact {
+  generatedAt: string | null;
+  entries: VirtualRouteEntry[];
+}
+
+/** RFC-0492: structured dossier fields for depth-1 industry records. */
+export interface IndustryDossierFields {
+  customerQuestions?: string[];
+  customerJourneys?: Array<{ title: string; stages: string[] }>;
+  serviceTaxonomy?: Array<{ category: string; description: string }>;
+  trustSignals?: string[];
+  evidenceRequirements?: string[];
+  contactModes?: string[];
+  serviceAreaModel?: string;
+  recommendedArchitecture?: Array<{ page: string; description: string }>;
+  suitableModules?: Array<{ module: string; applicability: string }>;
+  notdienst?: boolean;
+  industryFaq?: Array<{ question: string; answer: string }>;
+}

package/src/surface/visibility.ts

@@ -0,0 +1,57 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/surface/src/visibility.ts as an authored surface authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not model per-user analytics rows or external API clients.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0282: initial implementation of visibility feedback-loop contracts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const visibilitySourceSchema = z.enum(["gsc", "manual"]);
+
+export const clusterActionSchema = z.enum(["expand", "hold", "prune", "enrich", "escalate"]);
+
+export const visibilitySnapshotSchema = z.object({
+  clusterId: z.string().min(1),
+  windowStart: z.string().datetime(),
+  windowEnd: z.string().datetime(),
+  indexedPages: z.number().int().nonnegative(),
+  eligiblePages: z.number().int().nonnegative(),
+  impressions: z.number().int().nonnegative(),
+  clicks: z.number().int().nonnegative(),
+  uniqueQueries: z.number().int().nonnegative(),
+  avgPosition: z.number().positive().optional(),
+  source: visibilitySourceSchema,
+  importedAt: z.string().datetime(),
+  cannibalizingQueries: z.array(z.string().min(1)).optional(),
+  coreClicksBaseline: z.number().int().nonnegative().optional(),
+  coreClicksCurrent: z.number().int().nonnegative().optional(),
+});
+
+export const clusterOutcomeSchema = z.object({
+  clusterId: z.string().min(1),
+  surfaceId: z.string().min(1).optional(),
+  depth: z.number().int().nonnegative().optional(),
+  eligiblePages: z.number().int().nonnegative(),
+  indexedPages: z.number().int().nonnegative(),
+  impressions: z.number().int().nonnegative(),
+  clicks: z.number().int().nonnegative(),
+  uniqueQueries: z.number().int().nonnegative(),
+  indexationRate: z.number().min(0),
+  medianImpressionsPerPage: z.number().min(0),
+  queryDiversityShare: z.number().min(0),
+  positiveDemand: z.boolean(),
+  anomalies: z.array(z.string().min(1)),
+  proposedAction: clusterActionSchema,
+  rationale: z.string().min(1),
+});
+
+export type VisibilitySource = z.infer<typeof visibilitySourceSchema>;
+export type ClusterAction = z.infer<typeof clusterActionSchema>;
+export type VisibilitySnapshot = z.infer<typeof visibilitySnapshotSchema>;
+export type ClusterOutcome = z.infer<typeof clusterOutcomeSchema>;

package/src/surface/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig/node-lib.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "src/**/*.template.*",
+    "src/**/*.test.ts",
+    "src/**/tests/**",
+    "dist/**",
+    "node_modules/**"
+  ]
+}