@contractspec/lib.contracts-spec 2.0.0

package/dist/docs/views/index.js

@@ -0,0 +1,1031 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/registry-utils.ts
+var exports_registry_utils = {};
+__export(exports_registry_utils, {
+  groupByToArray: () => groupByToArray,
+  groupByMultiple: () => groupByMultiple,
+  groupBy: () => groupBy,
+  getUniqueTags: () => getUniqueTags,
+  getUniqueOwners: () => getUniqueOwners,
+  getUniqueDomains: () => getUniqueDomains,
+  filterBy: () => filterBy,
+  GroupingStrategies: () => GroupingStrategies
+});
+function filterBy(items, filter) {
+  return items.filter((item) => {
+    if (filter.tags?.length) {
+      const hasMatchingTag = filter.tags.some((tag) => item.meta.tags?.includes(tag));
+      if (!hasMatchingTag)
+        return false;
+    }
+    if (filter.owners?.length) {
+      const hasMatchingOwner = filter.owners.some((owner) => item.meta.owners?.includes(owner));
+      if (!hasMatchingOwner)
+        return false;
+    }
+    if (filter.stability?.length) {
+      if (!filter.stability.includes(item.meta.stability ?? "stable")) {
+        return false;
+      }
+    }
+    if (filter.domain) {
+      const itemDomain = GroupingStrategies.byDomain(item);
+      if (itemDomain !== filter.domain)
+        return false;
+    }
+    if (filter.keyPattern) {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      const pattern = filter.keyPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      if (!regex.test(name))
+        return false;
+    }
+    return true;
+  });
+}
+function groupBy(items, keyFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      groups.set(key, [item]);
+    }
+  }
+  return groups;
+}
+function groupByToArray(items, keyFn) {
+  const map = groupBy(items, keyFn);
+  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 }));
+}
+function groupByMultiple(items, keysFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const keys = keysFn(item);
+    for (const key of keys) {
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(item);
+      } else {
+        groups.set(key, [item]);
+      }
+    }
+  }
+  return groups;
+}
+function getUniqueTags(items) {
+  const tags = new Set;
+  for (const item of items) {
+    for (const tag of item.meta.tags ?? []) {
+      tags.add(tag);
+    }
+  }
+  return Array.from(tags).sort();
+}
+function getUniqueOwners(items) {
+  const owners = new Set;
+  for (const item of items) {
+    for (const owner of item.meta.owners ?? []) {
+      owners.add(owner);
+    }
+  }
+  return Array.from(owners).sort();
+}
+function getUniqueDomains(items) {
+  const domains = new Set;
+  for (const item of items) {
+    domains.add(GroupingStrategies.byDomain(item));
+  }
+  return Array.from(domains).sort();
+}
+var GroupingStrategies;
+var init_registry_utils = __esm(() => {
+  GroupingStrategies = {
+    byTag: (item) => item.meta.tags?.[0] ?? "untagged",
+    byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
+    byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
+    byDomain: (item) => {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      return name.split(".")[0] ?? "default";
+    },
+    byStability: (item) => item.meta.stability ?? "stable",
+    byUrlPath: (level) => (item) => {
+      if (!item.path)
+        return "root";
+      const segments = item.path.split("/").filter(Boolean);
+      return segments.slice(0, level).join("/") || "root";
+    }
+  };
+});
+
+// src/ownership.ts
+var StabilityEnum = {
+  Idea: "idea",
+  InCreation: "in_creation",
+  Experimental: "experimental",
+  Beta: "beta",
+  Stable: "stable",
+  Deprecated: "deprecated"
+};
+var OwnersEnum = {
+  PlatformCore: "platform.core",
+  PlatformSigil: "platform.sigil",
+  PlatformMarketplace: "platform.marketplace",
+  PlatformMessaging: "platform.messaging",
+  PlatformContent: "platform.content",
+  PlatformFeatureFlags: "platform.featureflags",
+  PlatformFinance: "platform.finance"
+};
+var Owners = OwnersEnum;
+var TagsEnum = {
+  Spots: "spots",
+  Collectivity: "collectivity",
+  Marketplace: "marketplace",
+  Sellers: "sellers",
+  Auth: "auth",
+  Login: "login",
+  Signup: "signup",
+  Guide: "guide",
+  Docs: "docs",
+  I18n: "i18n",
+  Incident: "incident",
+  Automation: "automation",
+  Hygiene: "hygiene"
+};
+var Tags = TagsEnum;
+
+// src/operations/operation.ts
+var isEmitDeclRef = (e) => ("ref" in e);
+var defineCommand = (spec) => ({
+  ...spec,
+  meta: { ...spec.meta, kind: "command" },
+  policy: {
+    ...spec.policy,
+    idempotent: spec.policy?.["policy"]?.idempotent ?? false
+  }
+});
+var defineQuery = (spec) => ({
+  ...spec,
+  meta: { ...spec.meta, kind: "query" },
+  policy: { ...spec.policy, idempotent: true }
+});
+
+// src/registry.ts
+init_registry_utils();
+import { compareVersions } from "compare-versions";
+var keyOfSpecContract = (spec) => `${spec.meta.key}.v${spec.meta.version}`;
+
+class SpecContractRegistry {
+  contractType;
+  items = new Map;
+  constructor(contractType, items) {
+    this.contractType = contractType;
+    if (items) {
+      items.forEach((p) => this.register(p));
+    }
+  }
+  register(p) {
+    const key = keyOfSpecContract(p);
+    if (this.items.has(key))
+      throw new Error(`Duplicate contract \`${this.contractType}\` ${key}`);
+    this.items.set(key, p);
+    return this;
+  }
+  count() {
+    return this.items.size;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(`${key}.v${version}`);
+    let candidate;
+    for (const [k, p] of this.items.entries()) {
+      if (!k.startsWith(`${key}.v`))
+        continue;
+      if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) {
+        candidate = p;
+      }
+    }
+    return candidate;
+  }
+  has(key, version) {
+    return !!this.get(key, version);
+  }
+  filter(criteria) {
+    return filterBy(this.list(), criteria);
+  }
+  listByTag(tag) {
+    return this.list().filter((p) => p.meta.tags?.includes(tag));
+  }
+  listByOwner(owner) {
+    return this.list().filter((p) => p.meta.owners?.includes(owner));
+  }
+  groupBy(keyFn) {
+    return groupBy(this.list(), keyFn);
+  }
+  getUniqueTags() {
+    return getUniqueTags(this.list());
+  }
+}
+
+// src/events.ts
+function defineEvent(e) {
+  return e;
+}
+var eventKey = (key, version) => `${key}.v${version}`;
+
+class EventRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("event", items);
+  }
+}
+
+// src/operations/registry.ts
+function opKey(key, version) {
+  return `${key}.v${version}`;
+}
+
+class OperationSpecRegistry extends SpecContractRegistry {
+  handlers = new Map;
+  constructor(items) {
+    super("operation", items);
+  }
+  bind(spec, handler) {
+    const key = opKey(spec.meta.key, spec.meta.version);
+    if (!this.items.has(key))
+      throw new Error(`Cannot bind; spec not found: ${key}`);
+    if (this.handlers.has(key))
+      throw new Error(`Handler already bound for ${key}`);
+    this.handlers.set(key, handler);
+    return this;
+  }
+  getHandler(key, version) {
+    const spec = this.get(key, version);
+    if (!spec)
+      return;
+    return this.handlers.get(opKey(spec.meta.key, spec.meta.version));
+  }
+  listBound() {
+    const out = [];
+    for (const [k, spec] of this.items.entries()) {
+      const h = this.handlers.get(k);
+      if (h)
+        out.push({ spec, handler: h });
+    }
+    return out;
+  }
+  async execute(key, version, rawInput, ctx) {
+    const baseSpec = this.get(key, version);
+    if (!baseSpec)
+      throw new Error(`Spec not found for ${key}${version ? `.v${version}` : ""}`);
+    const spec = await ctx.specVariantResolver?.resolve({
+      name: baseSpec.meta.key,
+      version: baseSpec.meta.version,
+      kind: baseSpec.meta.kind
+    }, ctx) ?? baseSpec;
+    let handlerKey = opKey(spec.meta.key, spec.meta.version);
+    let handler = this.handlers.get(handlerKey);
+    if (!handler) {
+      const fallbackKey = opKey(baseSpec.meta.key, baseSpec.meta.version);
+      handler = this.handlers.get(fallbackKey);
+      handlerKey = fallbackKey;
+    }
+    if (!handler)
+      throw new Error(`No handler bound for ${handlerKey}`);
+    const parsedInput = spec.io.input?.getZod().parse(rawInput);
+    if (ctx.decide) {
+      const [service, command] = spec.meta.key.split(".");
+      if (!service || !command)
+        throw new Error(`Invalid spec name: ${spec.meta.key}`);
+      const decision = await ctx.decide({
+        service,
+        command,
+        version: spec.meta.version,
+        actor: ctx.actor ?? "anonymous",
+        channel: ctx.channel,
+        roles: ctx.roles,
+        organizationId: ctx.organizationId,
+        userId: ctx.userId,
+        flags: []
+      });
+      if (decision.effect === "deny") {
+        throw new Error(`PolicyDenied: ${spec.meta.key}.v${spec.meta.version}`);
+      }
+      if (decision.rateLimit && ctx.rateLimit) {
+        const key2 = decision.rateLimit.key ?? "default";
+        const rpm = decision.rateLimit.rpm ?? 60;
+        await ctx.rateLimit(key2, 1, rpm);
+      }
+    }
+    const allowedEvents = new Map;
+    if (spec.sideEffects?.emits) {
+      for (const e of spec.sideEffects.emits) {
+        if (isEmitDeclRef(e)) {
+          const eventSpec = ctx.eventSpecResolver?.get(e.ref.key, e.ref.version);
+          if (eventSpec) {
+            allowedEvents.set(`${e.ref.key}.v${e.ref.version}`, eventSpec.payload);
+          }
+        } else {
+          allowedEvents.set(`${e.key}.v${e.version}`, e.payload);
+        }
+      }
+    }
+    const emitGuard = async (eventName, eventVersion, payload) => {
+      const key2 = eventKey(eventName, eventVersion);
+      const schema = allowedEvents.get(key2);
+      if (!schema)
+        throw new Error(`UndeclaredEvent: ${key2} not allowed by ${opKey(spec.meta.key, spec.meta.version)}`);
+      const parsed = schema.getZod().parse(payload);
+      await ctx.eventPublisher?.({
+        key: eventName,
+        version: eventVersion,
+        payload: parsed,
+        traceId: ctx.traceId
+      });
+    };
+    if (ctx.appConfig) {
+      if (!ctx.branding) {
+        ctx.branding = ctx.appConfig.branding;
+      }
+      if (!ctx.translation) {
+        ctx.translation = { config: ctx.appConfig.translation };
+      } else if (!ctx.translation.config) {
+        ctx.translation = {
+          ...ctx.translation,
+          config: ctx.appConfig.translation
+        };
+      }
+    }
+    const telemetryContext = ctx.telemetry;
+    const trackTelemetry = async (trigger, details) => {
+      if (!telemetryContext || !trigger?.event)
+        return;
+      try {
+        const props = trigger.properties?.(details) ?? {};
+        await telemetryContext.track(trigger.event.key, trigger.event.version ?? "1.0.0", props, {
+          tenantId: ctx.organizationId ?? undefined,
+          organizationId: ctx.organizationId,
+          userId: ctx.userId,
+          actor: ctx.actor,
+          channel: ctx.channel,
+          metadata: ctx.traceId ? { traceId: ctx.traceId } : undefined
+        });
+      } catch (_error) {}
+    };
+    let result;
+    try {
+      result = await handler(parsedInput, {
+        ...ctx,
+        __emitGuard__: emitGuard
+      });
+    } catch (error) {
+      if (spec.telemetry?.failure) {
+        await trackTelemetry(spec.telemetry.failure, {
+          input: parsedInput ?? rawInput,
+          error
+        });
+      }
+      throw error;
+    }
+    if (spec.telemetry?.success) {
+      await trackTelemetry(spec.telemetry.success, {
+        input: parsedInput ?? rawInput,
+        output: result
+      });
+    }
+    const outputModel = spec.io.output;
+    if (outputModel?.getZod) {
+      const parsedOutput = outputModel.getZod().parse(result);
+      return parsedOutput;
+    }
+    return result;
+  }
+}
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/data-views/spec.ts
+function defineDataView(spec) {
+  return spec;
+}
+
+// src/data-views/registry.ts
+function dataViewKey(spec) {
+  return `${spec.meta.key}.v${spec.meta.version}`;
+}
+
+class DataViewRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("data-view", items);
+  }
+}
+// src/docs/constants.ts
+var DOCS_DOMAIN = "docs";
+var DOCS_OWNERS = ["docs-platform"];
+var DOCS_TAGS = ["docs", "documentation"];
+var DOCS_STABILITY = StabilityEnum.Experimental;
+
+// src/docs/tech/docs-system.docblock.ts
+var docsSystemDocBlocks = [
+  {
+    id: "docs.tech.docs-system",
+    title: "Docs system overview",
+    summary: "How ContractSpec generates, indexes, and presents documentation.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/system",
+    tags: ["docs", "system", "contracts"],
+    body: `# Docs system overview
+
+ContractSpec treats documentation as a first-class output of your specs. The docs system combines:
+
+- Contract operations and schemas
+- DocBlocks (goal/how/usage/reference)
+- Presentations for rendering
+
+The result is a consistent docs surface across CLI, web, and MCP.
+
+## Key surfaces
+
+- Generation: \`docs.generate\`
+- Index/search: \`docs.search\`
+- Contract reference: \`docs.contract.reference\`
+- Publish: \`docs.publish\`
+`
+  },
+  {
+    id: "docs.tech.docs-generator",
+    title: "Docs generator",
+    summary: "Generate reference docs and metadata from ContractSpecs.",
+    kind: "how",
+    visibility: "public",
+    route: "/docs/tech/docs/generator",
+    tags: ["docs", "generator", "cli"],
+    body: `# Docs generator
+
+The generator produces documentation artifacts from registered ContractSpecs and DocBlocks.
+
+## Outputs
+
+- Reference pages for operations, events, forms, data views, and presentations
+- Search index metadata (DocBlocks + routes)
+- Contract schemas rendered to markdown or JSON
+`
+  },
+  {
+    id: "docs.tech.docs-search",
+    title: "Docs index and search",
+    summary: "Search DocBlocks by query, tag, kind, or visibility.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/search",
+    tags: ["docs", "search"],
+    body: `# Docs index and search
+
+The docs index is the canonical list of DocBlocks exposed to UI and MCP surfaces.
+
+## Query
+
+- Operation: \`docs.search\`
+- Filters: query, tag, kind, visibility
+`
+  },
+  {
+    id: "docs.tech.docs-reference",
+    title: "Contract reference pages",
+    summary: "Resolve any spec into a docs-ready reference payload.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/reference",
+    tags: ["docs", "reference"],
+    body: `# Contract reference
+
+Contract reference pages are generated from spec metadata plus schema details.
+
+## Query
+
+- Operation: \`docs.contract.reference\`
+`
+  },
+  {
+    id: "docs.tech.docs-publish",
+    title: "Docs publish",
+    summary: "Publish generated artifacts to the docs host.",
+    kind: "how",
+    visibility: "public",
+    route: "/docs/tech/docs/publish",
+    tags: ["docs", "publish"],
+    body: `# Docs publish
+
+Publishing moves generated artifacts to a hosting target with versioning.
+
+## Command
+
+- Operation: \`docs.publish\`
+`
+  },
+  {
+    id: "docs.tech.docs-examples",
+    title: "Examples catalog",
+    summary: "Document and surface example projects with sandbox support.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/docs/examples",
+    tags: ["docs", "examples"],
+    body: `# Examples catalog
+
+Examples are registered as ExampleSpecs and surface DocBlocks for discovery.
+
+- Docs index tags should include \`examples\` to populate the catalog.
+- Sandbox support is available under \`/sandbox\`.
+`
+  }
+];
+registerDocBlocks(docsSystemDocBlocks);
+// src/docs/queries/docsIndex.query.ts
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+var DocSummaryModel = new SchemaModel({
+  name: "DocSummary",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    summary: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    route: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    visibility: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    kind: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    version: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    }
+  }
+});
+var DocsIndexInput = new SchemaModel({
+  name: "DocsIndexInput",
+  fields: {
+    query: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    tag: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    },
+    visibility: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    kind: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    offset: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var DocsIndexOutput = new SchemaModel({
+  name: "DocsIndexOutput",
+  fields: {
+    items: { type: DocSummaryModel, isOptional: true, isArray: true },
+    docs: { type: DocSummaryModel, isOptional: false, isArray: true },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    nextOffset: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var DocsIndexQuery = defineQuery({
+  meta: {
+    key: "docs.search",
+    title: "Docs Index",
+    version: "1.0.0",
+    description: "Search and filter DocBlocks by query, tag, or visibility.",
+    goal: "Provide a consistent index of documentation entries for UI and MCP.",
+    context: "Used by docs surfaces to list and filter DocBlocks without coupling to storage.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "search", "index"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-search")]
+  },
+  capability: {
+    key: "docs.system",
+    version: "1.0.0"
+  },
+  io: {
+    input: DocsIndexInput,
+    output: DocsIndexOutput
+  },
+  policy: {
+    auth: "anonymous",
+    pii: []
+  }
+});
+
+// src/docs/queries/contractReference.query.ts
+import { ScalarTypeEnum as ScalarTypeEnum2, SchemaModel as SchemaModel2 } from "@contractspec/lib.schema";
+var ContractReferenceInput = new SchemaModel2({
+  name: "ContractReferenceInput",
+  fields: {
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    format: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    includeSchema: { type: ScalarTypeEnum2.Boolean(), isOptional: true }
+  }
+});
+var ContractReferenceModel = new SchemaModel2({
+  name: "ContractReference",
+  fields: {
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    description: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    markdown: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    route: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    schema: { type: ScalarTypeEnum2.JSONObject(), isOptional: true },
+    policy: { type: ScalarTypeEnum2.JSONObject(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    },
+    owners: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true,
+      isArray: true
+    },
+    stability: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
+  }
+});
+var ContractReferenceOutput = new SchemaModel2({
+  name: "ContractReferenceOutput",
+  fields: {
+    reference: { type: ContractReferenceModel, isOptional: false }
+  }
+});
+var ContractReferenceQuery = defineQuery({
+  meta: {
+    key: "docs.contract.reference",
+    title: "Contract Reference",
+    version: "1.0.0",
+    description: "Resolve a contract into a documentation-ready reference.",
+    goal: "Expose a canonical reference view for any ContractSpec surface.",
+    context: "Used by docs generators and UI to render consistent reference pages.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "reference"],
+    stability: DOCS_STABILITY,
+    docId: [docId("docs.tech.docs-reference")]
+  },
+  capability: {
+    key: "docs.system",
+    version: "1.0.0"
+  },
+  io: {
+    input: ContractReferenceInput,
+    output: ContractReferenceOutput
+  },
+  policy: {
+    auth: "anonymous",
+    pii: []
+  }
+});
+
+// src/docs/views/docsIndex.dataView.ts
+var DocsIndexDataView = defineDataView({
+  meta: {
+    key: "docs.index.view",
+    title: "Docs Index",
+    version: "1.0.0",
+    description: "List and filter documentation entries.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "index"],
+    stability: DOCS_STABILITY,
+    entity: "docs",
+    docId: [docId("docs.tech.docs-search")]
+  },
+  source: {
+    primary: {
+      key: DocsIndexQuery.meta.key,
+      version: DocsIndexQuery.meta.version
+    }
+  },
+  view: {
+    kind: "list",
+    fields: [
+      { key: "id", label: "ID", dataPath: "id" },
+      { key: "title", label: "Title", dataPath: "title" },
+      { key: "summary", label: "Summary", dataPath: "summary" },
+      { key: "route", label: "Route", dataPath: "route" },
+      { key: "tags", label: "Tags", dataPath: "tags", format: "badge" },
+      { key: "kind", label: "Kind", dataPath: "kind" },
+      { key: "visibility", label: "Visibility", dataPath: "visibility" }
+    ],
+    primaryField: "title",
+    secondaryFields: ["summary", "route"],
+    filters: [
+      { key: "query", label: "Search", field: "query", type: "search" },
+      {
+        key: "visibility",
+        label: "Visibility",
+        field: "visibility",
+        type: "enum",
+        options: [
+          { value: "public", label: "Public" },
+          { value: "internal", label: "Internal" },
+          { value: "mixed", label: "Mixed" }
+        ]
+      },
+      {
+        key: "kind",
+        label: "Kind",
+        field: "kind",
+        type: "enum",
+        options: [
+          { value: "goal", label: "Goal" },
+          { value: "how", label: "How" },
+          { value: "usage", label: "Usage" },
+          { value: "reference", label: "Reference" },
+          { value: "faq", label: "FAQ" },
+          { value: "changelog", label: "Changelog" }
+        ]
+      }
+    ]
+  },
+  policy: {
+    flags: [],
+    pii: []
+  }
+});
+
+// src/docs/views/contractReference.dataView.ts
+var ContractReferenceDataView = defineDataView({
+  meta: {
+    key: "docs.contract.reference.view",
+    title: "Contract Reference",
+    version: "1.0.0",
+    description: "Detail view for a single contract reference.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "reference"],
+    stability: DOCS_STABILITY,
+    entity: "contract-reference",
+    docId: [docId("docs.tech.docs-reference")]
+  },
+  source: {
+    primary: {
+      key: ContractReferenceQuery.meta.key,
+      version: ContractReferenceQuery.meta.version
+    }
+  },
+  view: {
+    kind: "detail",
+    fields: [
+      {
+        key: "key",
+        label: "Key",
+        dataPath: "reference.key"
+      },
+      {
+        key: "version",
+        label: "Version",
+        dataPath: "reference.version"
+      },
+      {
+        key: "type",
+        label: "Type",
+        dataPath: "reference.type"
+      },
+      {
+        key: "title",
+        label: "Title",
+        dataPath: "reference.title"
+      },
+      {
+        key: "description",
+        label: "Description",
+        dataPath: "reference.description",
+        format: "markdown"
+      },
+      {
+        key: "tags",
+        label: "Tags",
+        dataPath: "reference.tags"
+      },
+      {
+        key: "owners",
+        label: "Owners",
+        dataPath: "reference.owners"
+      },
+      {
+        key: "stability",
+        label: "Stability",
+        dataPath: "reference.stability"
+      }
+    ],
+    primaryField: "title",
+    secondaryFields: ["description"]
+  },
+  policy: {
+    flags: [],
+    pii: []
+  }
+});
+
+// src/docs/views/exampleCatalog.dataView.ts
+var ExampleCatalogDataView = defineDataView({
+  meta: {
+    key: "docs.examples.catalog.view",
+    title: "Examples Catalog",
+    version: "1.0.0",
+    description: "Catalog view of ContractSpec examples and demos.",
+    domain: DOCS_DOMAIN,
+    owners: DOCS_OWNERS,
+    tags: [...DOCS_TAGS, "examples"],
+    stability: DOCS_STABILITY,
+    entity: "docs-examples",
+    docId: [docId("docs.tech.docs-examples")]
+  },
+  source: {
+    primary: {
+      key: DocsIndexQuery.meta.key,
+      version: DocsIndexQuery.meta.version
+    }
+  },
+  view: {
+    kind: "grid",
+    fields: [
+      { key: "id", label: "ID", dataPath: "id" },
+      { key: "title", label: "Title", dataPath: "title" },
+      { key: "summary", label: "Summary", dataPath: "summary" },
+      { key: "route", label: "Route", dataPath: "route" },
+      { key: "tags", label: "Tags", dataPath: "tags", format: "badge" }
+    ],
+    primaryField: "title",
+    secondaryFields: ["summary"],
+    filters: [
+      { key: "query", label: "Search", field: "query", type: "search" },
+      {
+        key: "tags",
+        label: "Tags",
+        field: "tag",
+        type: "enum",
+        options: [
+          { value: "examples", label: "Examples" },
+          { value: "templates", label: "Templates" },
+          { value: "sandbox", label: "Sandbox" }
+        ]
+      }
+    ]
+  },
+  policy: {
+    flags: [],
+    pii: []
+  }
+});
+export {
+  ExampleCatalogDataView,
+  DocsIndexDataView,
+  ContractReferenceDataView
+};