@contractspec/bundle.library 3.7.6 → 3.8.2

package/src/components/docs/safety/SafetyMigrationsPage.tsx

@@ -8,88 +8,88 @@ import { ChevronRight } from 'lucide-react';
 // };
 
 export function SafetyMigrationsPage() {
-  return (
-    <div className="space-y-8">
-      <div className="space-y-4">
-        <h1 className="text-4xl font-bold">Migrations</h1>
-        <p className="text-muted-foreground">
-          A <strong>schema migration</strong> (also called a database migration)
-          is a set of incremental, reversible changes to a database schema.
-          According to{' '}
-          <a
-            href="https://en.wikipedia.org/wiki/Schema_migration"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="text-violet-400 hover:text-violet-300"
-          >
-            Wikipedia
-          </a>
-          , schema migrations "allow the database schema to evolve as the
-          application's requirements change, while preserving existing data."
-        </p>
-      </div>
+	return (
+		<div className="space-y-8">
+			<div className="space-y-4">
+				<h1 className="font-bold text-4xl">Migrations</h1>
+				<p className="text-muted-foreground">
+					A <strong>schema migration</strong> (also called a database migration)
+					is a set of incremental, reversible changes to a database schema.
+					According to{' '}
+					<a
+						href="https://en.wikipedia.org/wiki/Schema_migration"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="text-violet-400 hover:text-violet-300"
+					>
+						Wikipedia
+					</a>
+					, schema migrations "allow the database schema to evolve as the
+					application's requirements change, while preserving existing data."
+				</p>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Why migrations matter</h2>
-        <p className="text-muted-foreground">
-          As your application evolves, you'll need to change your data
-          model—adding new fields, renaming tables, changing data types, or
-          restructuring relationships. Without a disciplined approach, these
-          changes can lead to:
-        </p>
-        <ul className="text-muted-foreground list-inside list-disc space-y-2">
-          <li>Data loss or corruption</li>
-          <li>Downtime during deployments</li>
-          <li>
-            Inconsistencies between environments (dev, staging, production)
-          </li>
-          <li>Difficulty rolling back failed changes</li>
-        </ul>
-        <p className="text-muted-foreground">
-          Migrations solve these problems by treating schema changes as
-          versioned, tested, and reversible operations.
-        </p>
-      </div>
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Why migrations matter</h2>
+				<p className="text-muted-foreground">
+					As your application evolves, you'll need to change your data
+					model—adding new fields, renaming tables, changing data types, or
+					restructuring relationships. Without a disciplined approach, these
+					changes can lead to:
+				</p>
+				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
+					<li>Data loss or corruption</li>
+					<li>Downtime during deployments</li>
+					<li>
+						Inconsistencies between environments (dev, staging, production)
+					</li>
+					<li>Difficulty rolling back failed changes</li>
+				</ul>
+				<p className="text-muted-foreground">
+					Migrations solve these problems by treating schema changes as
+					versioned, tested, and reversible operations.
+				</p>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">How MigrationSpec works</h2>
-        <p className="text-muted-foreground">
-          In ContractSpec, migrations are defined using{' '}
-          <strong>MigrationSpec</strong>. Each migration has:
-        </p>
-        <ul className="text-muted-foreground list-inside list-disc space-y-2">
-          <li>
-            <strong>Version</strong> – A unique identifier (e.g.,
-            "2025-11-13-001") that determines the order of execution.
-          </li>
-          <li>
-            <strong>Up function</strong> – The forward migration that applies
-            the change (e.g., "add column 'email_verified'").
-          </li>
-          <li>
-            <strong>Down function</strong> – The reverse migration that undoes
-            the change (e.g., "drop column 'email_verified'").
-          </li>
-          <li>
-            <strong>Dependencies</strong> – Other migrations that must run
-            before this one.
-          </li>
-          <li>
-            <strong>Validation</strong> – Optional checks to ensure the
-            migration succeeded (e.g., "verify all users have an email
-            address").
-          </li>
-        </ul>
-      </div>
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">How MigrationSpec works</h2>
+				<p className="text-muted-foreground">
+					In ContractSpec, migrations are defined using{' '}
+					<strong>MigrationSpec</strong>. Each migration has:
+				</p>
+				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
+					<li>
+						<strong>Version</strong> – A unique identifier (e.g.,
+						"2025-11-13-001") that determines the order of execution.
+					</li>
+					<li>
+						<strong>Up function</strong> – The forward migration that applies
+						the change (e.g., "add column 'email_verified'").
+					</li>
+					<li>
+						<strong>Down function</strong> – The reverse migration that undoes
+						the change (e.g., "drop column 'email_verified'").
+					</li>
+					<li>
+						<strong>Dependencies</strong> – Other migrations that must run
+						before this one.
+					</li>
+					<li>
+						<strong>Validation</strong> – Optional checks to ensure the
+						migration succeeded (e.g., "verify all users have an email
+						address").
+					</li>
+				</ul>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Example MigrationSpec</h2>
-        <p className="text-muted-foreground">
-          Here's a migration that adds an email verification field to the users
-          table:
-        </p>
-        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
-          <pre>{`migrationId: add-email-verified
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Example MigrationSpec</h2>
+				<p className="text-muted-foreground">
+					Here's a migration that adds an email verification field to the users
+					table:
+				</p>
+				<div className="overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm">
+					<pre>{`migrationId: add-email-verified
 version: 2025-11-13-001
 dependencies: []
 
@@ -113,119 +113,119 @@ validation:
       SELECT COUNT(*) FROM users
       WHERE email_verified IS NULL;
     expectZeroRows: true`}</pre>
-        </div>
-      </div>
+				</div>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Running migrations</h2>
-        <p className="text-muted-foreground">
-          Migrations are applied automatically during deployment. The
-          ContractSpec runtime:
-        </p>
-        <ol className="text-muted-foreground list-inside list-decimal space-y-2">
-          <li>
-            Checks which migrations have already been applied (stored in a
-            migrations table).
-          </li>
-          <li>Identifies new migrations that need to run.</li>
-          <li>Executes them in order, respecting dependencies.</li>
-          <li>Runs validation checks to ensure success.</li>
-          <li>Records the migration as applied.</li>
-        </ol>
-        <p className="text-muted-foreground">
-          If a migration fails, the deployment is aborted, and the system
-          remains in its previous state. You can then fix the migration and
-          redeploy.
-        </p>
-      </div>
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Running migrations</h2>
+				<p className="text-muted-foreground">
+					Migrations are applied automatically during deployment. The
+					ContractSpec runtime:
+				</p>
+				<ol className="list-inside list-decimal space-y-2 text-muted-foreground">
+					<li>
+						Checks which migrations have already been applied (stored in a
+						migrations table).
+					</li>
+					<li>Identifies new migrations that need to run.</li>
+					<li>Executes them in order, respecting dependencies.</li>
+					<li>Runs validation checks to ensure success.</li>
+					<li>Records the migration as applied.</li>
+				</ol>
+				<p className="text-muted-foreground">
+					If a migration fails, the deployment is aborted, and the system
+					remains in its previous state. You can then fix the migration and
+					redeploy.
+				</p>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Rolling back migrations</h2>
-        <p className="text-muted-foreground">
-          If you need to roll back a deployment, ContractSpec automatically runs
-          the <strong>down</strong> functions of any migrations that were
-          applied. This restores the database to its previous state.
-        </p>
-        <p className="text-muted-foreground">
-          Note that rollbacks are not always possible—for example, if you've
-          deleted a column, you cannot recover the data unless you have a
-          backup. For destructive changes, it's best to use a multi-step
-          migration:
-        </p>
-        <ol className="text-muted-foreground list-inside list-decimal space-y-2">
-          <li>Add the new column (reversible).</li>
-          <li>
-            Backfill data from the old column to the new column (reversible).
-          </li>
-          <li>Update application code to use the new column (reversible).</li>
-          <li>
-            Drop the old column (irreversible—only do this after confirming the
-            new column works).
-          </li>
-        </ol>
-      </div>
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Rolling back migrations</h2>
+				<p className="text-muted-foreground">
+					If you need to roll back a deployment, ContractSpec automatically runs
+					the <strong>down</strong> functions of any migrations that were
+					applied. This restores the database to its previous state.
+				</p>
+				<p className="text-muted-foreground">
+					Note that rollbacks are not always possible—for example, if you've
+					deleted a column, you cannot recover the data unless you have a
+					backup. For destructive changes, it's best to use a multi-step
+					migration:
+				</p>
+				<ol className="list-inside list-decimal space-y-2 text-muted-foreground">
+					<li>Add the new column (reversible).</li>
+					<li>
+						Backfill data from the old column to the new column (reversible).
+					</li>
+					<li>Update application code to use the new column (reversible).</li>
+					<li>
+						Drop the old column (irreversible—only do this after confirming the
+						new column works).
+					</li>
+				</ol>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Best practices</h2>
-        <ul className="text-muted-foreground list-inside list-disc space-y-2">
-          <li>
-            <strong>Test migrations locally</strong> – Run them against a copy
-            of production data to catch issues before deploying.
-          </li>
-          <li>
-            <strong>Keep migrations small</strong> – Each migration should do
-            one thing. This makes them easier to understand and roll back.
-          </li>
-          <li>
-            <strong>Write reversible migrations</strong> – Always provide a down
-            function, even if you don't plan to roll back.
-          </li>
-          <li>
-            <strong>Use transactions</strong> – Wrap migrations in database
-            transactions so they either fully succeed or fully fail.
-          </li>
-          <li>
-            <strong>Avoid destructive changes</strong> – Prefer additive changes
-            (adding columns) over destructive ones (dropping columns). If you
-            must delete data, archive it first.
-          </li>
-          <li>
-            <strong>Version your migrations</strong> – Use timestamps or
-            sequential numbers to ensure migrations run in the correct order.
-          </li>
-          <li>
-            <strong>Document breaking changes</strong> – If a migration requires
-            application code changes, note this in the migration description.
-          </li>
-        </ul>
-      </div>
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Best practices</h2>
+				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
+					<li>
+						<strong>Test migrations locally</strong> – Run them against a copy
+						of production data to catch issues before deploying.
+					</li>
+					<li>
+						<strong>Keep migrations small</strong> – Each migration should do
+						one thing. This makes them easier to understand and roll back.
+					</li>
+					<li>
+						<strong>Write reversible migrations</strong> – Always provide a down
+						function, even if you don't plan to roll back.
+					</li>
+					<li>
+						<strong>Use transactions</strong> – Wrap migrations in database
+						transactions so they either fully succeed or fully fail.
+					</li>
+					<li>
+						<strong>Avoid destructive changes</strong> – Prefer additive changes
+						(adding columns) over destructive ones (dropping columns). If you
+						must delete data, archive it first.
+					</li>
+					<li>
+						<strong>Version your migrations</strong> – Use timestamps or
+						sequential numbers to ensure migrations run in the correct order.
+					</li>
+					<li>
+						<strong>Document breaking changes</strong> – If a migration requires
+						application code changes, note this in the migration description.
+					</li>
+				</ul>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Zero-downtime migrations</h2>
-        <p className="text-muted-foreground">
-          Some migrations can cause downtime if not handled carefully. For
-          example, adding a NOT NULL column to a large table can lock the table
-          for minutes. To avoid this, use a multi-step approach:
-        </p>
-        <ol className="text-muted-foreground list-inside list-decimal space-y-2">
-          <li>Add the column as nullable.</li>
-          <li>Backfill the column in batches (without locking the table).</li>
-          <li>Add the NOT NULL constraint once all rows are populated.</li>
-        </ol>
-        <p className="text-muted-foreground">
-          ContractSpec's migration system supports this pattern by allowing you
-          to split a logical change into multiple versioned migrations.
-        </p>
-      </div>
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Zero-downtime migrations</h2>
+				<p className="text-muted-foreground">
+					Some migrations can cause downtime if not handled carefully. For
+					example, adding a NOT NULL column to a large table can lock the table
+					for minutes. To avoid this, use a multi-step approach:
+				</p>
+				<ol className="list-inside list-decimal space-y-2 text-muted-foreground">
+					<li>Add the column as nullable.</li>
+					<li>Backfill the column in batches (without locking the table).</li>
+					<li>Add the NOT NULL constraint once all rows are populated.</li>
+				</ol>
+				<p className="text-muted-foreground">
+					ContractSpec's migration system supports this pattern by allowing you
+					to split a logical change into multiple versioned migrations.
+				</p>
+			</div>
 
-      <div className="flex items-center gap-4 pt-4">
-        <Link href="/docs/safety/auditing" className="btn-ghost">
-          Previous: Audit Logs
-        </Link>
-        <Link href="/docs/advanced/renderers" className="btn-primary">
-          Next: Advanced Topics <ChevronRight size={16} />
-        </Link>
-      </div>
-    </div>
-  );
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/safety/auditing" className="btn-ghost">
+					Previous: Audit Logs
+				</Link>
+				<Link href="/docs/advanced/renderers" className="btn-primary">
+					Next: Advanced Topics <ChevronRight size={16} />
+				</Link>
+			</div>
+		</div>
+	);
 }

package/src/components/docs/safety/SafetyOverviewPage.tsx

@@ -1,164 +1,77 @@
 import Link from '@contractspec/lib.ui-link';
-import { ChevronRight } from 'lucide-react';
 
-// export const metadata = {
-//   title: 'Safety Overview: ContractSpec Docs',
-//   description:
-//     "Learn about ContractSpec's safety features: spec signing, policy decision points, audit logs, migrations, and more.",
-// };
+const safetyPages = [
+	{
+		title: 'Spec signing',
+		body: 'Protect the integrity of what gets deployed and make changes verifiable.',
+		href: '/docs/safety/signing',
+	},
+	{
+		title: 'Policy decision points',
+		body: 'Apply governance consistently across operations, data access, and generated surfaces.',
+		href: '/docs/safety/pdp',
+	},
+	{
+		title: 'Audit trails',
+		body: 'Record operational and policy decisions with enough context to inspect and explain them later.',
+		href: '/docs/safety/auditing',
+	},
+	{
+		title: 'Migrations',
+		body: 'Evolve data and schema boundaries without losing control of the system.',
+		href: '/docs/safety/migrations',
+	},
+	{
+		title: 'Tenant isolation',
+		body: 'Keep configuration, access rules, and sensitive data bounded by tenant.',
+		href: '/docs/safety/tenant-isolation',
+	},
+	{
+		title: 'Security and trust',
+		body: 'Understand the trust model, release process, and security expectations around the OSS system.',
+		href: '/docs/safety/security-trust',
+	},
+];
 
 export function SafetyOverviewPage() {
-  return (
-    <div className="space-y-8">
-      <div className="space-y-4">
-        <h1 className="text-4xl font-bold">Safety Overview</h1>
-        <p className="text-muted-foreground">
-          ContractSpec is designed with <strong>safety by default</strong>.
-          Every operation is governed by policies, every change is audited, and
-          every deployment is reversible. This section covers the core safety
-          mechanisms that protect your application and data.
-        </p>
-      </div>
+	return (
+		<div className="space-y-10">
+			<div className="space-y-3">
+				<p className="editorial-kicker">Operate</p>
+				<h1 className="font-serif text-4xl tracking-[-0.04em] md:text-5xl">
+					Safety is part of the system model, not an afterthought.
+				</h1>
+				<p className="max-w-3xl text-lg text-muted-foreground leading-8">
+					ContractSpec is meant to survive real change: new generated surfaces,
+					policy updates, migrations, integration churn, and operator handoffs.
+					The safety layer makes those changes inspectable, reversible, and
+					governed.
+				</p>
+			</div>
 
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Core safety features</h2>
-        <div className="space-y-6">
-          <div className="space-y-2">
-            <h3 className="text-xl font-semibold">
-              <Link
-                href="/docs/safety/signing"
-                className="text-violet-400 hover:text-violet-300"
-              >
-                Spec Signing
-              </Link>
-            </h3>
-            <p className="text-muted-foreground">
-              All specifications are cryptographically signed before deployment.
-              This ensures that only authorized changes reach production and
-              that specs cannot be tampered with in transit or at rest.
-              Signatures are verified at runtime, and unsigned specs are
-              rejected.
-            </p>
-          </div>
+			<div className="editorial-proof-strip">
+				<div className="editorial-stat">
+					<span className="editorial-label">Operating rule</span>
+					<span className="editorial-stat-value">
+						explicit change beats hidden mutation
+					</span>
+				</div>
+				<p className="max-w-2xl text-muted-foreground text-sm leading-7">
+					Use policies, signing, audit trails, and migrations to keep the system
+					legible even as AI-assisted workflows accelerate change volume.
+				</p>
+			</div>
 
-          <div className="space-y-2">
-            <h3 className="text-xl font-semibold">
-              <Link
-                href="/docs/safety/pdp"
-                className="text-violet-400 hover:text-violet-300"
-              >
-                Policy Decision Points (PDP)
-              </Link>
-            </h3>
-            <p className="text-muted-foreground">
-              Every API call, UI render, and data access passes through a
-              centralized Policy Decision Point. The PDP evaluates
-              attribute-based access control (ABAC) rules and PII policies to
-              determine whether the operation is allowed. This ensures
-              consistent enforcement across your entire application.
-            </p>
-          </div>
-
-          <div className="space-y-2">
-            <h3 className="text-xl font-semibold">
-              <Link
-                href="/docs/safety/auditing"
-                className="text-violet-400 hover:text-violet-300"
-              >
-                Audit Logs
-              </Link>
-            </h3>
-            <p className="text-muted-foreground">
-              ContractSpec automatically records every operation in
-              tamper-evident audit logs. These logs capture who did what, when,
-              and why—including policy decisions, data access, and
-              administrative actions. Audit logs are essential for compliance,
-              security investigations, and debugging.
-            </p>
-          </div>
-
-          <div className="space-y-2">
-            <h3 className="text-xl font-semibold">
-              <Link
-                href="/docs/safety/migrations"
-                className="text-violet-400 hover:text-violet-300"
-              >
-                Migrations
-              </Link>
-            </h3>
-            <p className="text-muted-foreground">
-              Schema and data migrations are managed through{' '}
-              <strong>MigrationSpecs</strong>. Each migration is versioned,
-              reversible, and tested before deployment. This allows you to
-              evolve your application safely without downtime or data loss.
-            </p>
-          </div>
-
-          <div className="space-y-2">
-            <h3 className="text-xl font-semibold">Dark Launch & Rollback</h3>
-            <p className="text-muted-foreground">
-              New features can be deployed in "dark launch" mode, where they run
-              in production but are not visible to users. This allows you to
-              test performance and correctness with real traffic before enabling
-              the feature. If issues arise, you can instantly roll back to the
-              previous version without redeploying.
-            </p>
-          </div>
-
-          <div className="space-y-2">
-            <h3 className="text-xl font-semibold">Data Classification</h3>
-            <p className="text-muted-foreground">
-              Fields in your specs can be tagged with sensitivity levels (e.g.,
-              PII, PHI, confidential). The policy engine uses these tags to
-              enforce access controls, redaction rules, and data retention
-              policies automatically. This reduces the risk of accidental data
-              leaks.
-            </p>
-          </div>
-        </div>
-      </div>
-
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Why safety matters</h2>
-        <p className="text-muted-foreground">
-          Modern applications handle sensitive data and critical operations. A
-          single bug or misconfiguration can lead to data breaches, compliance
-          violations, or service outages. ContractSpec's safety features are not
-          optional add-ons—they are built into the core platform and enforced
-          automatically.
-        </p>
-        <p className="text-muted-foreground">
-          By making safety the default, ContractSpec allows you to move fast
-          without breaking things. You can deploy new features confidently,
-          knowing that policies are enforced, changes are audited, and rollbacks
-          are always available.
-        </p>
-      </div>
-
-      <div className="space-y-4">
-        <h2 className="text-2xl font-bold">Next steps</h2>
-        <p className="text-muted-foreground">
-          Explore each safety feature in detail using the links above, or
-          continue with the advanced topics:
-        </p>
-        <div className="flex flex-wrap gap-4 pt-4">
-          <Link href="/docs/safety/signing" className="btn-primary">
-            Spec Signing <ChevronRight size={16} className="inline" />
-          </Link>
-          <Link href="/docs/safety/pdp" className="btn-ghost">
-            Policy Decision Points <ChevronRight size={16} className="inline" />
-          </Link>
-          <Link href="/docs/safety/auditing" className="btn-ghost">
-            Audit Logs <ChevronRight size={16} className="inline" />
-          </Link>
-          <Link href="/docs/safety/migrations" className="btn-ghost">
-            Migrations <ChevronRight size={16} className="inline" />
-          </Link>
-          <Link href="/docs/safety/security-trust" className="btn-ghost">
-            Security & Trust <ChevronRight size={16} className="inline" />
-          </Link>
-        </div>
-      </div>
-    </div>
-  );
+			<div className="grid gap-4 md:grid-cols-2">
+				{safetyPages.map((page) => (
+					<Link key={page.href} href={page.href} className="editorial-panel">
+						<h2 className="font-semibold text-xl">{page.title}</h2>
+						<p className="mt-2 text-muted-foreground text-sm leading-7">
+							{page.body}
+						</p>
+					</Link>
+				))}
+			</div>
+		</div>
+	);
 }