@contractspec/bundle.library 3.8.12 → 3.9.0

package/dist/components/docs/specs/SpecsBuilderControlPlanePage.js

@@ -1,5 +1,5 @@
 // @bun
-import{CodeBlock as o}from"@contractspec/lib.design-system";import r from"@contractspec/lib.ui-link";import{jsx as e,jsxs as t}from"react/jsx-runtime";var i=[{title:"Managed",body:"Best when the team wants the platform to own setup, routing, readiness, and mobile-safe defaults."},{title:"Local",body:"Best for power users who want tenant-local execution providers and tighter data-locality control."},{title:"Hybrid",body:"Best when some work should stay local while preview, review, or export flows still use managed coordination."}],n=["Capture prompts, files, voice, and other inbound sources into a typed workspace instead of relying on a single chat transcript.","Fuse the sources into decisions, assumptions, and blueprint updates with provenance and approval memory.","Compile authoring work into execution lanes, then route the work to explicit provider profiles and runtime targets.","Create previews, run readiness gates, and record receipts before export becomes an operator action.","Keep mobile review parity so approvals, incidents, and patch proposals can be inspected away from the desktop workbench."];function c(){return t("div",{className:"space-y-10",children:[t("section",{className:"space-y-3",children:[e("p",{className:"editorial-kicker",children:"Spec pack"}),e("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Builder is a governed authoring control plane, not a frontier coding agent."}),t("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:["The implemented Builder stack sits across"," ",e("code",{children:"@contractspec/lib.builder-spec"}),","," ",e("code",{children:"@contractspec/lib.builder-runtime"}),","," ",e("code",{children:"@contractspec/lib.provider-spec"}),", and the reusable workbench/mobile modules. It orchestrates inputs, provider routing, readiness, and export decisions on top of the OSS ContractSpec foundation and the Studio operating layer."]})]}),t("section",{className:"editorial-proof-strip",children:[t("div",{className:"editorial-stat",children:[e("span",{className:"editorial-label",children:"What Builder owns"}),e("span",{className:"editorial-stat-value",children:"fusion, routing, readiness, export"})]}),e("p",{className:"max-w-2xl text-muted-foreground text-sm leading-7",children:"Builder delegates synthesis and coding to external execution providers. Its job is to keep those runs policy-aware, provenance-rich, and usable from both desktop and mobile operator surfaces."})]}),t("section",{className:"editorial-panel space-y-5",children:[t("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Implemented stack and entrypoints"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"You can use the type surfaces directly in code, or start from the already wired workbench and mobile review routes in the public app shell."})]}),e(o,{language:"text",filename:"builder-stack",code:`Packages
+import{CodeBlock as o}from"@contractspec/lib.design-system";import r from"@contractspec/lib.ui-link";import{jsx as e,jsxs as a}from"react/jsx-runtime";var i=[{title:"Managed",body:"Best when the team wants the platform to own setup, routing, readiness, API defaults, and mobile-safe operator flows."},{title:"Local",body:"Best for power users who want local-daemon registration, tenant-local execution providers, and tighter data-locality control."},{title:"Hybrid",body:"Best when some work should stay local while preview, review, export, or mobile operator flows still use managed coordination."}],n=["Bootstrap managed, local-daemon, or hybrid presets explicitly instead of inventing provider posture ad hoc per host.","Capture prompts, files, voice, and other inbound sources into a typed workspace instead of relying on a single chat transcript.","Fuse the sources into decisions, assumptions, and blueprint updates with provenance and approval memory.","Compile authoring work into execution lanes, then route the work to explicit provider profiles and runtime targets.","Create previews, run readiness gates, and record receipts before export becomes an operator action.","Keep mobile review parity so approvals, incidents, and patch proposals can be inspected away from the desktop workbench."],s=["local trust and lease posture for registered local runtimes","channel-action and comparison posture data in the shared Builder snapshot","preview, readiness, export, and mobile-review state derived from the same workspace snapshot"];function p(){return a("div",{className:"space-y-10",children:[a("section",{className:"space-y-3",children:[e("p",{className:"editorial-kicker",children:"Spec pack"}),e("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Builder is a governed authoring control plane, not a frontier coding agent."}),a("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:["The implemented Builder stack sits across"," ",e("code",{children:"@contractspec/lib.builder-spec"}),","," ",e("code",{children:"@contractspec/lib.builder-runtime"}),","," ",e("code",{children:"@contractspec/lib.provider-spec"}),", and the reusable workbench/mobile modules. It orchestrates inputs, provider routing, readiness, and export decisions on top of the OSS ContractSpec foundation and the Studio operating layer."]})]}),a("section",{className:"editorial-proof-strip",children:[a("div",{className:"editorial-stat",children:[e("span",{className:"editorial-label",children:"What Builder owns"}),e("span",{className:"editorial-stat-value",children:"fusion, routing, readiness, export"})]}),e("p",{className:"max-w-2xl text-muted-foreground text-sm leading-7",children:"Builder delegates synthesis and coding to external execution providers. Its job is to keep those runs policy-aware, provenance-rich, and usable from both desktop and mobile operator surfaces."})]}),a("section",{className:"editorial-panel space-y-5",children:[a("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Implemented stack and entrypoints"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"You can use the type surfaces directly in code, or start from the already wired workbench and mobile review routes in the public app shell."})]}),e(o,{language:"text",filename:"builder-stack",code:`Packages
 - @contractspec/lib.builder-spec
 - @contractspec/lib.builder-runtime
 - @contractspec/lib.provider-spec
@@ -13,7 +13,22 @@ Web app routes
 Operate API proxy
 - /api/operate/builder/queries/builder.workspace.snapshot
 - /api/operate/builder/commands/builder.blueprint.patch
-- /api/operate/builder/commands/builder.export.execute`})]}),e("section",{className:"grid gap-4 md:grid-cols-3",children:i.map((a)=>t("article",{className:"editorial-panel space-y-3",children:[e("h2",{className:"font-semibold text-xl",children:a.title}),e("p",{className:"text-muted-foreground text-sm leading-7",children:a.body})]},a.title))}),t("section",{className:"grid gap-5 lg:grid-cols-2",children:[t("article",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Typical Builder loop"}),e("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground text-sm leading-7",children:n.map((a)=>e("li",{children:a},a))})]}),t("article",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"What Builder should not become"}),t("ul",{className:"editorial-list",children:[t("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Not a competitor to specialized coding agents such as Codex or Claude Code."})]}),t("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Not a managed-only product that traps teams away from OSS-local runtime paths."})]}),t("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Not a hidden routing layer that obscures provider provenance, receipts, or runtime mode."})]}),t("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Not a desktop-only surface. Mobile review parity is part of the control-plane contract."})]})]})]})]}),t("section",{className:"editorial-panel space-y-5",children:[t("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Use the workbench UI as the host surface"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"The reusable module already exposes the desktop workbench shell. Your host app keeps control of action wiring, runtime mode selection, and approval flows."})]}),e(o,{language:"tsx",filename:"BuilderWorkbenchHost.tsx",code:`import { BuilderWorkbench, useBuilderWorkbenchState } from "@contractspec/module.builder-workbench";
+- /api/operate/builder/commands/builder.export.execute`})]}),e("section",{className:"grid gap-4 md:grid-cols-3",children:i.map((t)=>a("article",{className:"editorial-panel space-y-3",children:[e("h2",{className:"font-semibold text-xl",children:t.title}),e("p",{className:"text-muted-foreground text-sm leading-7",children:t.body})]},t.title))}),a("section",{className:"grid gap-5 lg:grid-cols-2",children:[a("article",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Typical Builder loop"}),e("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground text-sm leading-7",children:n.map((t)=>e("li",{children:t},t))})]}),a("article",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"What Builder should not become"}),a("ul",{className:"editorial-list",children:[a("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Not a competitor to specialized coding agents such as Codex or Claude Code."})]}),a("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Not a managed-only product that traps teams away from OSS-local runtime paths."})]}),a("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Not a hidden routing layer that obscures provider provenance, receipts, or runtime mode."})]}),a("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:"Not a desktop-only surface. Mobile review parity is part of the control-plane contract."})]})]})]})]}),a("section",{className:"editorial-panel space-y-5",children:[a("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Workspace config carries the current Builder defaults"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"Builder setup is no longer just an app-shell concern. The shared workspace config now carries runtime mode, bootstrap preset, control plane API defaults, and local runtime registration metadata so the CLI, editors, and web shells resolve the same posture."})]}),e(o,{language:"json",filename:".contractsrc.json",code:`{
+  "builder": {
+    "enabled": true,
+    "runtimeMode": "local",
+    "bootstrapPreset": "local_daemon_mvp",
+    "api": {
+      "baseUrl": "https://api.contractspec.io",
+      "controlPlaneTokenEnvVar": "CONTROL_PLANE_API_TOKEN"
+    },
+    "localRuntime": {
+      "runtimeId": "rt_local_daemon",
+      "grantedTo": "local:operator",
+      "providerIds": ["provider.codex", "provider.local.model"]
+    }
+  }
+}`})]}),a("section",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Operator posture stays visible"}),e("ul",{className:"editorial-list",children:s.map((t)=>a("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:t})]},t))})]}),a("section",{className:"editorial-panel space-y-5",children:[a("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Use the workbench UI as the host surface"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"The reusable module already exposes the desktop workbench shell. Your host app keeps control of action wiring, runtime mode selection, and approval flows."})]}),e(o,{language:"tsx",filename:"BuilderWorkbenchHost.tsx",code:`import { BuilderWorkbench, useBuilderWorkbenchState } from "@contractspec/module.builder-workbench";
 
 const state = useBuilderWorkbenchState({
   workspace: initialSnapshot.workspace,
@@ -31,4 +46,4 @@ const state = useBuilderWorkbenchState({
   onRunReadiness={runReadiness}
   onExecuteExport={executeExport}
   selectedExportRuntimeMode="hybrid"
-/>;`})]}),t("section",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Read this with the Studio bridge in mind"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"Builder is where the OSS foundation meets the richer operating layer. Use the Studio overview when you want the higher-level product posture and team workflows on top of these contracts."}),t("div",{className:"flex flex-wrap gap-3",children:[e(r,{href:"/docs/studio",className:"btn-primary",children:"Studio overview"}),e(r,{href:"/docs/architecture/control-plane",className:"btn-ghost",children:"Control-plane runtime"})]})]})]})}export{c as SpecsBuilderControlPlanePage};
+/>;`})]}),a("section",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Read this with the Studio bridge in mind"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"Builder is where the OSS foundation meets the richer operating layer. Use the Studio overview when you want the higher-level product posture and team workflows on top of these contracts."}),a("div",{className:"flex flex-wrap gap-3",children:[e(r,{href:"/docs/studio",className:"btn-primary",children:"Studio overview"}),e(r,{href:"/docs/architecture/control-plane",className:"btn-ghost",children:"Control-plane runtime"})]})]})]})}export{p as SpecsBuilderControlPlanePage};

package/dist/components/docs/specs/SpecsConnectPage.js

@@ -1,8 +1,10 @@
 // @bun
-import{CodeBlock as c}from"@contractspec/lib.design-system";import n from"@contractspec/lib.ui-link";import{jsx as e,jsxs as t}from"react/jsx-runtime";var o=[{title:"ContextPack",body:"Projects the current repo state, impacted contracts, canon packs, policy bindings, and acceptance checks into one task-scoped envelope."},{title:"PlanPacket",body:"Compiles a candidate objective into ACP-aware steps plus explicit refs back to control-plane intent, plan compile, and plan verify contracts."},{title:"PatchVerdict",body:"Classifies one file edit or shell command as permit, rewrite, require_review, or deny, with runtime-linked control-plane state when available."},{title:"ReviewPacket",body:"Persists the evidence a human needs when Connect escalates, while keeping the local artifact trail authoritative in OSS mode."}],i=["Enable `connect` in `.contractsrc.json` and keep your protected, immutable, generated, and smoke-check policies explicit.","Run `contractspec connect context` and `contractspec connect plan` before risky work so the agent is operating on task-scoped evidence, not ambient repo assumptions.","Gate file and shell mutations through `contractspec connect verify` or the host hook commands instead of inventing editor-specific approval logic.","Inspect pending review packets locally first, then sync them to the Studio bridge only if your team wants centralized operator workflows.","Use replay and harness evaluation to prove whether a prior decision stayed safe when the workspace changed."],s=["Connect is not a second control plane or a second package family.","Verdicts are projections over existing `controlPlane.*`, ACP, workspace, and harness primitives.","Studio is optional for baseline enforcement. Local artifacts remain the OSS source of truth.","Destructive commands, protected paths, drift, and unknown impact stay visible instead of being hidden behind adapter magic."];function p(){return t("div",{className:"space-y-10",children:[t("section",{className:"space-y-3",children:[e("p",{className:"editorial-kicker",children:"Spec pack"}),e("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"ContractSpec Connect puts coding-agent actions behind explicit, local-first governance."}),e("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"Connect is the adapter layer between agent-native actions and the existing ContractSpec stack. It reuses control-plane, ACP, workspace, knowledge, and harness primitives to explain what the agent is trying to do before a file edit or shell command lands."})]}),t("section",{className:"editorial-proof-strip",children:[t("div",{className:"editorial-stat",children:[e("span",{className:"editorial-label",children:"Authoritative surfaces"}),e("span",{className:"editorial-stat-value",children:"control plane, ACP, workspace, harness"})]}),e("p",{className:"max-w-2xl text-muted-foreground text-sm leading-7",children:"Connect stays narrow on purpose. It projects local evidence, maps its verdicts back to runtime semantics, and leaves the canonical system contracts where they already live."})]}),t("section",{className:"editorial-panel space-y-5",children:[t("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"What you use in practice"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"The CLI and the workspace service already implement the pack. The main workflow is local initialization, task projection, verification, then optional review sync."})]}),e(c,{language:"bash",filename:"contractspec-connect",code:`contractspec connect init --scope workspace
+import{CodeBlock as c}from"@contractspec/lib.design-system";import n from"@contractspec/lib.ui-link";import{jsx as e,jsxs as t}from"react/jsx-runtime";var o=[{title:"ContextPack",body:"Projects the current repo state, impacted contracts, canon packs, policy bindings, and acceptance checks into one task-scoped envelope."},{title:"PlanPacket",body:"Compiles a candidate objective into ACP-aware steps plus explicit refs back to control-plane intent, plan compile, and plan verify contracts."},{title:"PatchVerdict",body:"Classifies one file edit or shell command as permit, rewrite, require_review, or deny, with runtime-linked control-plane state when available."},{title:"ReviewPacket",body:"Persists the evidence a human needs when Connect escalates, while keeping the local artifact trail authoritative in OSS mode."}],i=["`.contractspec/adoption/catalog.json` mirrored from the bundled ContractSpec catalog","family-aware reuse recommendations for `ui`, `contracts`, `integrations`, `runtime`, `sharedLibs`, and `solutions`","verdict thresholds that can prefer workspace reuse, ContractSpec reuse, review, or explicit denial before a new implementation starts"],s=["Enable `connect` in `.contractsrc.json` and keep your protected, immutable, generated, and smoke-check policies explicit.","Run `contractspec connect context` and `contractspec connect plan` before risky work so the agent is operating on task-scoped evidence, not ambient repo assumptions.","Gate file and shell mutations through `contractspec connect verify` or the host hook commands instead of inventing editor-specific approval logic.","Inspect pending review packets locally first, then sync them to the Studio bridge only if your team wants centralized operator workflows.","Use replay and harness evaluation to prove whether a prior decision stayed safe when the workspace changed."],r=["Connect is not a second control plane or a second package family.","Verdicts are projections over existing `controlPlane.*`, ACP, workspace, and harness primitives.","Studio is optional for baseline enforcement. Local artifacts remain the OSS source of truth.","Destructive commands, protected paths, drift, and unknown impact stay visible instead of being hidden behind adapter magic."];function d(){return t("div",{className:"space-y-10",children:[t("section",{className:"space-y-3",children:[e("p",{className:"editorial-kicker",children:"Spec pack"}),e("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"ContractSpec Connect puts coding-agent actions behind explicit, local-first governance."}),e("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"Connect is the adapter layer between agent-native actions and the existing ContractSpec stack. It reuses control-plane, ACP, workspace, knowledge, and harness primitives to explain what the agent is trying to do before a file edit or shell command lands."})]}),t("section",{className:"editorial-proof-strip",children:[t("div",{className:"editorial-stat",children:[e("span",{className:"editorial-label",children:"Authoritative surfaces"}),e("span",{className:"editorial-stat-value",children:"control plane, ACP, workspace, harness"})]}),e("p",{className:"max-w-2xl text-muted-foreground text-sm leading-7",children:"Connect stays narrow on purpose. It projects local evidence, maps its verdicts back to runtime semantics, and leaves the canonical system contracts where they already live."})]}),t("section",{className:"editorial-panel space-y-5",children:[t("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"What you use in practice"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"The CLI and the workspace service already implement the pack. The main workflow is local initialization, task projection, verification, then optional review sync."})]}),e(c,{language:"bash",filename:"contractspec-connect",code:`contractspec connect init --scope workspace
+contractspec connect adoption sync --json
+printf '{"goal":"Prefer an existing release helper before adding a new one"}' | contractspec connect adoption resolve --family sharedLibs --stdin --json
 contractspec connect context --task refactor-docs --paths packages/libs/contracts-spec/src/control-plane/contracts.ts --json
 printf '{"objective":"Document the control-plane contract surface","commands":["bun run typecheck"]}' | contractspec connect plan --task refactor-docs --stdin --json
 printf '{"operation":"edit","path":"packages/libs/contracts-spec/src/control-plane/contracts.ts"}' | contractspec connect verify --task refactor-docs --tool acp.fs.access --stdin --json
 printf 'bun run typecheck' | contractspec connect verify --task refactor-docs --tool acp.terminal.exec --stdin --json
 contractspec connect review list --json
-contractspec connect replay <decisionId> --json`})]}),t("section",{className:"space-y-5",children:[t("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"The four core artifacts"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"Every Connect command is there to emit or inspect one of these reviewable objects under `.contractspec/connect/*`."})]}),e("div",{className:"grid gap-4 md:grid-cols-2",children:o.map((a)=>t("article",{className:"editorial-panel space-y-3",children:[e("h3",{className:"font-semibold text-xl",children:a.title}),e("p",{className:"text-muted-foreground text-sm leading-7",children:a.body})]},a.title))})]}),t("section",{className:"grid gap-5 lg:grid-cols-2",children:[t("article",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Adopt Connect in this order"}),e("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground text-sm leading-7",children:i.map((a)=>e("li",{children:a},a))})]}),t("article",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Boundaries that keep it trustworthy"}),e("ul",{className:"editorial-list",children:s.map((a)=>t("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:a})]},a))})]})]}),t("section",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Where Connect fits in the rest of the docs"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"Read the control-plane runtime page when you want the underlying governance contracts, then use the Studio bridge only if your team wants centralized review queues on top of the OSS-local evidence path."}),t("div",{className:"flex flex-wrap gap-3",children:[e(n,{href:"/docs/architecture/control-plane",className:"btn-primary",children:"Control-plane runtime"}),e(n,{href:"/docs/studio",className:"btn-ghost",children:"Studio bridge"})]})]})]})}export{p as SpecsConnectPage};
+contractspec connect replay <decisionId> --json`})]}),t("section",{className:"space-y-5",children:[t("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"The four core artifacts"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"Every Connect command is there to emit or inspect one of these reviewable objects under `.contractspec/connect/*`."})]}),e("div",{className:"grid gap-4 md:grid-cols-2",children:o.map((a)=>t("article",{className:"editorial-panel space-y-3",children:[e("h3",{className:"font-semibold text-xl",children:a.title}),e("p",{className:"text-muted-foreground text-sm leading-7",children:a.body})]},a.title))})]}),t("section",{className:"editorial-panel space-y-5",children:[t("div",{className:"space-y-2",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Reuse-first adoption is part of the workflow"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"Connect adoption keeps reuse guidance in the same local control surface. Before a new contract family, helper, or runtime abstraction lands, Connect can mirror the bundled catalog and resolve the best reuse candidate by family."})]}),e("ul",{className:"editorial-list",children:i.map((a)=>t("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:a})]},a))})]}),t("section",{className:"grid gap-5 lg:grid-cols-2",children:[t("article",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Adopt Connect in this order"}),e("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground text-sm leading-7",children:s.map((a)=>e("li",{children:a},a))})]}),t("article",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Boundaries that keep it trustworthy"}),e("ul",{className:"editorial-list",children:r.map((a)=>t("li",{children:[e("span",{className:"editorial-list-marker"}),e("span",{children:a})]},a))})]})]}),t("section",{className:"editorial-panel space-y-4",children:[e("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:"Where Connect fits in the rest of the docs"}),e("p",{className:"text-muted-foreground text-sm leading-7",children:"Read the control-plane runtime page when you want the underlying governance contracts, then use the Studio bridge only if your team wants centralized review queues on top of the OSS-local evidence path."}),t("div",{className:"flex flex-wrap gap-3",children:[e(n,{href:"/docs/architecture/control-plane",className:"btn-primary",children:"Control-plane runtime"}),e(n,{href:"/docs/studio",className:"btn-ghost",children:"Studio bridge"})]})]})]})}export{d as SpecsConnectPage};

package/dist/components/docs/specs/SpecsDataViewsPage.js

@@ -1,42 +1,49 @@
 // @bun
-import B from"@contractspec/lib.ui-link";import{ChevronRight as D}from"lucide-react";import{jsx as z,jsxs as A}from"react/jsx-runtime";function G(){return A("div",{className:"space-y-8",children:[A("div",{className:"space-y-4",children:[z("h1",{className:"font-bold text-4xl",children:"DataViews"}),A("p",{className:"text-muted-foreground",children:["A ",z("strong",{children:"DataViewSpec"})," describes how data should be queried, filtered, sorted, and presented to users. Runtime adapters execute optimized database queries and serve list views, detail views, and search interfaces while respecting policy constraints."]})]}),A("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Core concepts"}),A("div",{className:"space-y-3",children:[A("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Data sources"}),z("p",{className:"text-muted-foreground",children:"A DataView connects to one or more data sources\u2014databases, APIs, or other capabilities. You specify the source and the fields you want to expose."})]}),A("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Filtering"}),z("p",{className:"text-muted-foreground",children:`Define filters that users can apply to narrow down results. Filters can be simple (e.g., "status equals 'active'") or complex (e.g., "created within the last 30 days AND assigned to current user").`})]}),A("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Sorting"}),z("p",{className:"text-muted-foreground",children:"Specify which fields can be sorted and the default sort order. ContractSpec generates efficient database queries with proper indexes."})]}),A("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Pagination"}),z("p",{className:"text-muted-foreground",children:"DataViews automatically support pagination to handle large datasets. You can configure page size limits and cursor-based or offset-based pagination."})]}),A("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Aggregations"}),z("p",{className:"text-muted-foreground",children:"Compute aggregates like counts, sums, averages, and group-by operations. These are useful for dashboards and summary views."})]})]})]}),A("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Example DataViewSpec"}),z("p",{className:"text-muted-foreground",children:"Here's a DataView for listing orders in TypeScript:"}),z("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:z("pre",{children:`import { defineDataView } from '@contractspec/lib.contracts-spec';
-import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import F from"@contractspec/lib.ui-link";import{ChevronRight as G}from"lucide-react";import{jsx as z,jsxs as B}from"react/jsx-runtime";var H=`import { defineDataView } from '@contractspec/lib.contracts-spec/data-views';
+import { ListDataGridShowcaseRowsQuery } from '@contractspec/example.data-grid-showcase/contracts/data-grid-showcase.operation';
 
-export const OrderList = defineDataView({
+export const DataGridShowcaseDataView = defineDataView({
   meta: {
-    key: 'order.list',
+    key: 'examples.data-grid-showcase.table',
     version: '1.0.0',
-    description: 'List of recent orders',
+    entity: 'account',
+    title: 'Data Grid Showcase Table',
+    description:
+      'Declarative DataViewSpec for the ContractSpec table showcase.',
+    domain: 'examples',
+    owners: ['@platform.core'],
+    tags: ['examples', 'table', 'data-grid'],
+    stability: 'experimental',
   },
   source: {
-    type: 'database',
-    table: 'orders',
+    primary: {
+      key: ListDataGridShowcaseRowsQuery.meta.key,
+      version: ListDataGridShowcaseRowsQuery.meta.version,
+    },
   },
-  fields: [
-    { name: 'orderId', type: 'uuid', sortable: true },
-    { name: 'customerName', type: 'string', searchable: true },
-    { name: 'total', type: 'number', sortable: true },
-    { 
-      name: 'status', 
-      type: 'enum', 
-      values: ['pending', 'processing', 'shipped'],
-      filterable: true 
+  view: {
+    kind: 'table',
+    executionMode: 'client',
+    selection: 'multiple',
+    columnVisibility: true,
+    columnResizing: true,
+    columnPinning: true,
+    rowExpansion: {
+      fields: ['notes', 'renewalDate', 'lastActivityAt'],
     },
-    { 
-      name: 'createdAt', 
-      type: 'timestamp', 
-      sortable: true, 
-      defaultSort: 'desc' 
+    initialState: {
+      pageSize: 4,
+      hiddenColumns: ['notes'],
+      pinnedColumns: {
+        left: ['account'],
+      },
+      sorting: [{ field: 'arr', desc: true }],
     },
-  ],
-  filters: [
-    { name: 'status', field: 'status', operator: 'in' },
-    { name: 'dateRange', field: 'createdAt', operator: 'between' },
-    { name: 'minTotal', field: 'total', operator: 'gte' },
-  ],
-  pagination: {
-    type: 'cursor',
-    defaultPageSize: 50,
-    maxPageSize: 200,
+    fields: [
+      { key: 'account', label: 'Account', dataPath: 'account', sortable: true },
+      { key: 'owner', label: 'Owner', dataPath: 'owner', sortable: true },
+      { key: 'status', label: 'Status', dataPath: 'status', sortable: true },
+      { key: 'notes', label: 'Notes', dataPath: 'notes' },
+    ],
   },
-});`})})]}),A("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Policy integration"}),A("p",{className:"text-muted-foreground",children:["DataViews automatically enforce"," ",z(B,{href:"/docs/specs/policy",className:"text-violet-400 hover:text-violet-300",children:"PolicySpecs"}),". If a user doesn't have permission to see certain fields, those fields are automatically filtered out or redacted. If a user can only see their own data, the query is automatically scoped."]}),z("p",{className:"text-muted-foreground",children:"This means you define the data view once, and it works correctly for all users based on their permissions\u2014no need to write separate queries for different roles."})]}),A("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Served outputs"}),z("p",{className:"text-muted-foreground",children:"From a DataViewSpec, ContractSpec serves:"}),A("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[A("li",{children:[z("strong",{children:"Database queries"})," \u2013 Optimized SQL or NoSQL queries executed at runtime"]}),A("li",{children:[z("strong",{children:"API endpoints"})," \u2013 RESTful or GraphQL endpoints for fetching data"]}),A("li",{children:[z("strong",{children:"UI components"})," \u2013 List views, tables, cards, and detail views"]}),A("li",{children:[z("strong",{children:"Search interfaces"})," \u2013 Full-text search with autocomplete"]}),A("li",{children:[z("strong",{children:"Export functions"})," \u2013 CSV, JSON, or Excel exports"]})]})]}),A("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Best practices"}),A("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[z("li",{children:"Only expose fields that users actually need\u2014this improves performance and security."}),z("li",{children:"Use appropriate indexes for sortable and filterable fields."}),z("li",{children:"Set reasonable pagination limits to prevent performance issues."}),z("li",{children:"Use aggregations sparingly\u2014they can be expensive on large datasets."}),z("li",{children:"Test DataViews with realistic data volumes to ensure they perform well."})]})]}),A("div",{className:"flex items-center gap-4 pt-4",children:[z(B,{href:"/docs/specs/capabilities",className:"btn-ghost",children:"Previous: Capabilities"}),A(B,{href:"/docs/specs/workflows",className:"btn-primary",children:["Next: Workflows ",z(D,{size:16})]})]})]})}export{G as SpecsDataViewsPage};
+});`;function N(){return B("div",{className:"space-y-8",children:[B("div",{className:"space-y-4",children:[z("h1",{className:"font-bold text-4xl",children:"DataViews"}),B("p",{className:"text-muted-foreground",children:["A ",z("strong",{children:"DataViewSpec"})," describes how data should be queried, filtered, sorted, and presented to users. Runtime adapters execute optimized database queries and serve list views, detail views, and search interfaces while respecting policy constraints."]})]}),B("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Core concepts"}),B("div",{className:"space-y-3",children:[B("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Data sources"}),z("p",{className:"text-muted-foreground",children:"A DataView connects to one or more data sources\u2014databases, APIs, or other capabilities. You specify the source and the fields you want to expose."})]}),B("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Filtering"}),z("p",{className:"text-muted-foreground",children:`Define filters that users can apply to narrow down results. Filters can be simple (e.g., "status equals 'active'") or complex (e.g., "created within the last 30 days AND assigned to current user").`})]}),B("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Sorting"}),z("p",{className:"text-muted-foreground",children:"Specify which fields can be sorted and the default sort order. ContractSpec generates efficient database queries with proper indexes."})]}),B("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Pagination"}),z("p",{className:"text-muted-foreground",children:"DataViews automatically support pagination to handle large datasets. You can configure page size limits and cursor-based or offset-based pagination."})]}),B("div",{children:[z("h3",{className:"font-semibold text-lg",children:"Aggregations"}),z("p",{className:"text-muted-foreground",children:"Compute aggregates like counts, sums, averages, and group-by operations. These are useful for dashboards and summary views."})]})]})]}),B("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Example DataViewSpec"}),B("p",{className:"text-muted-foreground",children:["Here is the canonical table contract used by the live"," ",z(F,{href:"/docs/examples/data-grid-showcase",className:"text-[color:var(--rust)] underline underline-offset-4",children:"Data Grid Showcase"}),":"]}),z("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:z("pre",{children:H})}),z("p",{className:"text-muted-foreground text-sm",children:"This one contract drives the DataView lane, while the same rows and controller also feed the raw web primitive, native-first primitive, and composed design-system demos."})]}),B("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Policy integration"}),B("p",{className:"text-muted-foreground",children:["DataViews automatically enforce"," ",z(F,{href:"/docs/specs/policy",className:"text-violet-400 hover:text-violet-300",children:"PolicySpecs"}),". If a user doesn't have permission to see certain fields, those fields are automatically filtered out or redacted. If a user can only see their own data, the query is automatically scoped."]}),z("p",{className:"text-muted-foreground",children:"This means you define the data view once, and it works correctly for all users based on their permissions\u2014no need to write separate queries for different roles."})]}),B("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Served outputs"}),z("p",{className:"text-muted-foreground",children:"From a DataViewSpec, ContractSpec serves:"}),B("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[B("li",{children:[z("strong",{children:"Database queries"})," \u2013 Optimized SQL or NoSQL queries executed at runtime"]}),B("li",{children:[z("strong",{children:"API endpoints"})," \u2013 RESTful or GraphQL endpoints for fetching data"]}),B("li",{children:[z("strong",{children:"UI components"})," \u2013 List views, tables, cards, and detail views"]}),B("li",{children:[z("strong",{children:"Search interfaces"})," \u2013 Full-text search with autocomplete"]}),B("li",{children:[z("strong",{children:"Export functions"})," \u2013 CSV, JSON, or Excel exports"]})]})]}),B("div",{className:"space-y-4",children:[z("h2",{className:"font-bold text-2xl",children:"Best practices"}),B("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[z("li",{children:"Only expose fields that users actually need\u2014this improves performance and security."}),z("li",{children:"Use appropriate indexes for sortable and filterable fields."}),z("li",{children:"Set reasonable pagination limits to prevent performance issues."}),z("li",{children:"Use aggregations sparingly\u2014they can be expensive on large datasets."}),z("li",{children:"Test DataViews with realistic data volumes to ensure they perform well."})]})]}),B("div",{className:"flex items-center gap-4 pt-4",children:[z(F,{href:"/docs/specs/capabilities",className:"btn-ghost",children:"Previous: Capabilities"}),B(F,{href:"/docs/specs/workflows",className:"btn-primary",children:["Next: Workflows ",z(G,{size:16})]})]})]})}export{N as SpecsDataViewsPage};