# `@contentrain/types` [![npm version](https://img.shields.io/npm/v/%40contentrain%2Ftypes?label=%40contentrain%2Ftypes)](https://www.npmjs.com/package/@contentrain/types) [![GitHub source](https://img.shields.io/badge/source-Contentrain%2Fai-181717?logo=github)](https://github.com/Contentrain/ai/tree/main/packages/types) [![Docs](https://img.shields.io/badge/docs-ai.contentrain.io-0f172a)](https://ai.contentrain.io/reference/config) Shared TypeScript types for the Contentrain ecosystem. Start here: - [2-minute product demo](https://ai.contentrain.io/demo) - [Config and format reference](https://ai.contentrain.io/reference/config) This package is the common schema layer used by: - `@contentrain/mcp` - `contentrain` - `@contentrain/query` - `@contentrain/wp-import` - `@contentrain/emitter-astro` - `@contentrain/astro-kit` - `@contentrain/decide` It defines the stable type vocabulary for models, config, metadata, validation, scanning, context files, and provider contracts (enabling third-party RepoProvider implementations). ## When To Use It Use `@contentrain/types` when you are: - building tooling on top of Contentrain packages - sharing model/config types between packages in a workspace - authoring framework integrations or SDK extensions - consuming Contentrain JSON structures directly in TypeScript - implementing a custom `RepoProvider` for a new git backend ## Install ```bash pnpm add @contentrain/types ``` ## What It Exports Core unions: - `FieldType` - `ModelKind` - `ContentStatus` - `ContentSource` - `WorkflowMode` - `StackType` - `Platform` - `ContextSource` - `CollectionRuntimeFormat` - `LocaleStrategy` Core interfaces: - `FieldDef` - `ModelDefinition` - `ModelLocaleScope` - `ModelSummary` - `ContentrainConfig` - `Vocabulary` - `EntryMeta` - `AssetEntry` - `ValidationError` - `ValidationResult` - `ScaffoldTemplate` - `ScanCandidate` - `DuplicateGroup` - `GraphNode` - `ProjectGraph` - `ScanCandidatesResult` - `ScanSummaryResult` - `ContextJson` Execution/approval unions (see [Execution and approval contracts](#execution-and-approval-contracts)): - `RiskClass` - `ApprovalGate` - `GrantRejection` - `ApprovalMode` - `RunStatus` - `ScheduleKind` - `SourceDeltaOp` Storage/runtime helper types: - `SingletonContentFile` - `CollectionContentFile` - `DictionaryContentFile` - `CollectionEntry` - `CollectionContentOutput` - `DocumentEntry` - `DocumentContentOutput` - `SingletonMeta` - `CollectionMeta` - `DocumentMeta` - `DictionaryMeta` Normalize/plan types: - `NormalizePlan` - `NormalizePlanModel` - `NormalizePlanExtraction` - `NormalizePlanPatch` Provider contracts (re-exported from `provider.ts` — implement these to add a new git backend): - `RepoProvider` - `RepoReader` - `RepoWriter` - `ProviderCapabilities` - `FileChange` - `CommitAuthor` - `Commit` - `ApplyPlanInput` - `Branch` - `FileDiff` - `MergeResult` (includes optional `sync?: SyncResult` for local-worktree providers) - `LOCAL_CAPABILITIES` (const — capability set for LocalProvider) Git transaction types: - `SyncResult` - `ContentrainError` Validate functions (pure, dependency-free): - `validateSlug(slug)` — kebab-case slug validation - `validateEntryId(id)` — entry ID format validation - `validateLocale(locale, config)` — locale format + config support check - `resolveModelLocales(model, config)` — the locales a model's content is expected to cover: `model.locales` when it declares one, otherwise `config.locales.supported` (the default locale alone when `i18n: false`) - `describeModelLocaleScope(scope)` — name a resolved scope the way a validation message should quote it - `validateModelLocales(model, config)` — check a `locales` declaration is a subset of `config.locales.supported` - `detectSecrets(value)` — detect potential secrets in field values (provider-shaped patterns, plus an `api_key = …` assignment whose tail passes `looksLikeCredential`) - `validateFieldValue(value, fieldDef)` — full field schema validation (type, required, min/max, pattern, select) Serialize functions (pure, dependency-free): - `sortKeys(obj, fieldOrder?)` — recursive key sorting for canonical output - `canonicalStringify(data, fieldOrder?)` — deterministic JSON serialization - `generateEntryId()` — 12-char hex ID generation - `parseMarkdownFrontmatter(content)` — parse YAML frontmatter + body from markdown - `serializeMarkdownFrontmatter(data, body)` — serialize data + body into markdown frontmatter - `parseFrontmatterScalar(raw)` / `parseFrontmatterScalarString(raw)` / `splitFrontmatterList(inner)` — the scalar grammar those two are built on, exported because a second reader needs it (see [Frontmatter round trip](#frontmatter-round-trip)) Constants: - `CONTENTRAIN_DIR` — default `.contentrain` folder name - `CONTENTRAIN_BRANCH` — default `contentrain` branch name for content tracking - `PATH_PATTERNS` — file path conventions for models, content, meta. Content and meta paths both name the model: a document is `content/{domain}/{modelId}/{slug}/{locale}.md`. The patterns show the default `locale_strategy: 'file'`; a parity test in `@contentrain/mcp` holds them to what the resolvers actually produce - `SLUG_PATTERN` — regex for valid slugs - `ENTRY_ID_PATTERN` — regex for valid entry IDs - `LOCALE_PATTERN` — regex for valid locale codes - `CANONICAL_JSON` — serialization rules (indent, encoding, trailing newline, key sort) - `SECRET_PATTERNS` — provider-shaped regex patterns for secret detection (the generic `api_key` rule lives in `detectSecrets`, gated by `looksLikeCredential`) ## Stability This package is intended to be the shared public contract across the Contentrain ecosystem. In practice that means: - types exported from the package root are the public surface - packages should depend on these shared definitions instead of redefining domain types - breaking changes here should be treated as ecosystem-level breaking changes - the `RepoProvider` contract enables third-party implementations without depending on `@contentrain/mcp` internals ## Quick Example ```ts import type { ContentrainConfig, FieldDef, ModelDefinition, ValidationResult, } from '@contentrain/types' const fields: Record = { title: { type: 'string', required: true }, slug: { type: 'slug', required: true, unique: true }, } const model: ModelDefinition = { id: 'blog-post', name: 'Blog Post', kind: 'collection', domain: 'blog', i18n: true, title_field: 'title', // Optional. Absent means every locale in config.locales.supported; a subset // narrows validation for a partially-translated model. locales: ['en', 'tr'], fields, } const config: ContentrainConfig = { version: 1, stack: 'next', workflow: 'review', locales: { default: 'en', supported: ['en', 'tr'] }, domains: ['blog'], } const result: ValidationResult = { valid: true, errors: [], } ``` ## Import Style Type-only usage: ```ts import type { ModelDefinition, ContentrainConfig } from '@contentrain/types' ``` Mixed usage (types + runtime functions): ```ts import type { FieldDef, ValidationError } from '@contentrain/types' import { validateFieldValue, validateSlug, detectSecrets, canonicalStringify, parseMarkdownFrontmatter, } from '@contentrain/types' ``` Provider contract usage (for custom RepoProvider implementations): ```ts import type { RepoProvider, ProviderCapabilities } from '@contentrain/types' export class MyCustomProvider implements RepoProvider { readonly capabilities: ProviderCapabilities = { localWorktree: false, sourceRead: true, sourceWrite: true, pushRemote: true, branchProtection: true, pullRequestFallback: true, astScan: false, } // ...implement RepoProvider methods } ``` ## Studio Integration Studio (Nuxt 4, web) cannot import `@contentrain/mcp` directly because MCP depends on Node.js-only packages (`simple-git`, `@modelcontextprotocol/sdk`). The validate and serialize functions in this package are **pure, dependency-free, and browser-compatible** — designed for Studio to share the same validation contract as MCP. ### What Studio gets from `@contentrain/types` | Function | Use case | |---|---| | `validateSlug(slug)` | Form validation for document slugs | | `validateEntryId(id)` | Validate collection entry IDs | | `validateLocale(locale, config)` | Locale picker validation | | `resolveModelLocales(model, config)` | Which locales to show, or require, for one model | | `validateModelLocales(model, config)` | Validate a model's locale-coverage subset in a model editor | | `detectSecrets(value)` | Content editor secret detection warnings | | `validateFieldValue(value, fieldDef)` | Full field-level validation in content forms | | `canonicalStringify(data, fieldOrder?)` | Preview canonical JSON output | | `parseMarkdownFrontmatter(content)` | Document editor frontmatter parsing | | `serializeMarkdownFrontmatter(data, body)` | Document editor serialization | | `parseFrontmatterScalar(raw)` | One frontmatter scalar: booleans, null, numbers, quoted strings with escapes decoded | | `parseFrontmatterScalarString(raw)` | The same, always as a string — a SKU of `"007"` must not become `7` | | `splitFrontmatterList(inner)` | Split an inline array on commas outside quotes | | `generateEntryId()` | Client-side entry ID generation | | `SECRET_PATTERNS` | Extend or customize secret detection | | `looksLikeCredential(tail)` | Decide whether a value assigned to an API-key setting is a credential or documentation | ### What stays in MCP (not available to Studio directly) These require file system I/O or Node.js dependencies: - `checkRelationIntegrity()` — validates relation references against actual content files on disk - `validateProject()` — full project validation with file reading - `writeContent()` / `deleteContent()` — content persistence with git worktree - `resolveContentDir()` / `resolveJsonFilePath()` — path resolution with `node:path` ### Unique constraints and relation validation `validateFieldValue` handles schema-level checks. Two things require external state: - **Unique constraints** — need to check across all entries (Studio should query its API/store) - **Relation references** — need to verify target entries exist (Studio should query its content API) These are left to Studio's server-side or API layer to implement on top of the pure validation. ## Design Role `@contentrain/types` exists so every package in the monorepo speaks the same domain language. Examples: - MCP validates and writes `ModelDefinition` - CLI reads `ContextJson` - SDK codegen consumes `ModelDefinition` and `FieldDef` - AI rules align with the same model and workflow vocabulary - Studio uses the same validation functions in the browser - Third-party providers implement `RepoProvider` to plug into MCP This package should stay: - small - zero runtime dependencies - browser + Node.js compatible - stable - free of package-specific behavior ## Development From the monorepo root: ```bash pnpm --filter @contentrain/types build pnpm --filter @contentrain/types test pnpm --filter @contentrain/types typecheck ``` ## Related Packages - `@contentrain/mcp` - `contentrain` - `@contentrain/query` - `@contentrain/wp-import` - `@contentrain/emitter-astro` - `@contentrain/astro-kit` - `@contentrain/decide` ## Part of the Contentrain ecosystem Contentrain is a content governance ecosystem for teams and AI agents; agents work on the content through the [MCP server](https://ai.contentrain.io/packages/mcp). This package is one of the [open-source tools](https://github.com/Contentrain/ai) ([docs](https://ai.contentrain.io)); [Studio](https://github.com/Contentrain/studio) builds on the same types for team review and roles. The other parts are [Migrate](https://migrate.contentrain.io), which moves WordPress sites to Astro, and [Bridge](https://github.com/Contentrain/wordpress-bridge), a free WordPress plugin that exports a site as a Contentrain store. ## License MIT ## Migration contracts Shared shapes for the WordPress → static-site migration pipeline. They exist here — in the one MIT package every side may depend on — because the documents cross repository and license boundaries: a GPL WordPress plugin produces them, a proprietary migration service consumes them, an open emitter renders from them. | Contract | Role | |---|---| | `RawIR` | Source-faithful extraction of a WordPress site (posts, terms, menus, comments, media, redirects, and from the bridge rung SEO and routing) with provenance: which access rung produced it (`rest_public` → `rest_auth` → `wxr` → `bridge`). Unresolved references are kept and marked, never dropped. | | `CapabilityManifest` | Evidence-based inventory of what the site uses (SEO, forms, comments, i18n, ACF, …) — the input for migration planning and the "what happens to X" conversation. `access.achieved` is the highest source-access rung actually reached, or `null` when none was: a site behind an access wall still gets a manifest, and a producer that writes a rung it did not reach makes the coverage figures unreadable. | | `ProjectIR` | The reproducible model of the site: route model, layout families, component variants, query bindings, design tokens. Not "this page's HTML" — the design system that generates unseen pages correctly. | | `MigrationHandoff` | What the migration hands the user: repository, per-capability dispositions, and offers for runtime capabilities (with cost comparison) — offering is this document's job; fulfilling is the receiving product's. `runtime` (`RuntimeBinding`) records where the generated site's runtime components were bound once an offer was fulfilled. `content_summary.body_kinds` counts standalone pages by `PageBodyKind` — `html` (editor markup, still editable), `builder_html` (rendered by a page builder, carried as rendered), `none` (the theme renders it) — because each promises something different to the person receiving the site. `plan_hash` and `order_id` (both optional) say which run and which order wrote the document, so a reader can tell a handoff left by an earlier delivery from the current one; absent means unknown, never stale. An offer marked `chosen` is the one the order picked for its capability; a reader hides the alternatives. `notes` are plain-English lines for the customer, never telemetry or a verdict. `MIGRATION_HANDOFF_GOLDEN` is the document a Migrate delivery writes, published so the producer's test and a reader's test use the same bytes. | | `RuntimeBinding` | The provider's public API origin (`base_url`) and `project_id` — all a static site needs to mount comments and forms. Never a credential: the public endpoints are unauthenticated by design. | All are plain JSON (snake_case keys), stamped with `MIGRATION_CONTRACT_VERSION`. `RawIR` also carries six optional parts from the bridge rung: - **`seo`** (`RawSeo`) holds which plugin serves the head (`serving`: `yoast` / `rank_math` / `aioseo` / `seopress` / `wordpress-core`; `seopress` may be absent from `providers` in an older export), each provider's status and settings, and each page's values keyed by `post:` or `term::` — plus `home`, one block per provider, for a home page that lists posts (a static front page is its page's `post:`). `status: 'none'` is an answer, not a missing export: no SEO plugin, and WordPress core renders only the title. `resolved: true` marks values the running plugin rendered; `false` marks stored values and templates only. `robots_served` is what the page actually carries after WordPress core and the plugin reconcile it. For a plugin that does not serve the head, `rendered` holds its templates as the exporter rendered them (`rendered_by`, e.g. `bridge`): final text, with each variable it could not render taken out of the string and named in `unresolved`, and `template_source` saying whether each template was the page's own, its post type's or the plugin default. `rendered.open_graph` / `rendered.twitter` carry `image_width` / `image_height` for a local attachment, and `rendered.schema.graph` the schema nodes the plugin stored for the page (Rank Math), their variables rendered. - **`acf_options`** (`RawAcfOptionsPage[]`) holds each ACF Options Page — site-wide fields that belong to no post — with its `slug`, `title`, the ACF storage `post_id` it is read from and its `fields`, keyed and shaped like `RawPost.acf`. Default-language values only; secret fields are left out as on a post. - **`routing`** (`RawRouting`) states the URL rules that `RawPost.link` holds as facts: permalink structure, bases, the front and posts pages, and each post type's and taxonomy's permastruct, with `with_front` applied. - **`redirects_excluded`** (`RawRedirectExcluded`) lists every rule a source holds that the site does not serve as a plain redirect, with the reason (`disabled`, `source-inactive`, `conditional-match:*`, `not-a-redirect:*`, …). Served plus excluded accounts for the whole table. - **`hardcoded_text`** (`RawHardcodedText`) accounts for the interface text outside the content tables — theme templates, scripts, widgets, menus, options, Customizer mods and rendered pages. Each `RawTextCandidate` has one outcome: `transfer` to a `target` (`dictionary:ui-strings`, `theme-settings.`, `site.title`, `site.description`, `content:wp-menu-items`) or `exclude` with a `reason` (`TEXT_EXCLUDE_REASONS`); a source that could not be read is listed in `errors`. Candidates merge only when text, locale and context are equal, and `key` depends on text and context only. Page text that also appears in source is `rendered-from-source` with `related` pointing at the source candidate, so the same words never land twice. `totals` closes: transfer + exclude = candidates, and error = `errors.length`. - **`integrations`** (`RawIntegration[]`) lists the outside services the site is connected to (`INTEGRATION_CATEGORIES`: analytics, crm, newsletter, ads, comments, captcha, cdn, other), each with its evidence. Evidence names a plugin, a setting, a script host, a form's wiring or an embed host, never a value. `reconnect_required` is `false` only for an embed, which has no account. `secret_present` says a credential is set on WordPress; the credential itself is never exported. `IntegrationReconnectRequiredIssue` (`code: 'integration_reconnect_required'`) is the one intake/handoff issue that lists every service to connect again. `RawRedirect` gains `id`, `match` and `regex`. Only `match: 'url'` without `regex` is a one-to-one mapping. A consumer that writes a regex or prefix rule as a literal `from` produces the wrong redirect. Chrome markers the emitter honours: `CHROME_BODY_SLOT` (where page content goes), `CHROME_REPEAT_OPEN`/`CHROME_IF_OPEN` (per-item and conditional regions), `LIST_ITEMS_SLOT` (where a list section's items go) and `componentSlot(id)` (``, where a `ComponentDef` — a `comments` thread, a `form` — is mounted). `ModelDefinition` can carry runtime-owned `form` and `comments` configuration. `MODEL_EXTENSION_KEYS` identifies these preserved blocks; canonical model serialization places them after `fields`. The content engine does not interpret the runtime settings. ## Execution and approval contracts `migration.ts` describes a site. `execution.ts` describes an act upon one — an agent run, a bulk edit, a deploy, a cutover — and who had to say yes first. Three repositories meet here and none may define these shapes for itself. The migration engine produces plans and receipts, Studio renders the plan card and collects approvals, and MCP is where a plan's steps execute. If each wrote its own `RiskClass`, "destructive" would mean three different things and the approval guarding it would be theatre. | Contract | Role | |---|---| | `RiskClass` | What is at stake, as an ordered ladder: `read_only` → `low_risk_content` → `bulk_content` → `destructive_schema` → `external_effect` → `financially_material` → `deployment`. `highestRisk()` rates a list of steps by the worst one (`effectiveRisk()` does it for a plan) — a survey that ends in a deploy is a deploy. | | `ApprovalGate` | The three distinct decision moments: `plan` (before the work, on scope and cost), `change` (on the produced diff), `release` (on production effect). Approving what will be done is not approving what was produced, and neither is permission to publish it. | | `ApprovalRule` / `ApprovalPolicyFile` | `.contentrain/approval-policies.json` — which risk needs whose approval, in which mode (`auto` / `single` / `quorum`). In git, beside the content it governs, so the policy in force is the policy on the branch. Rules are additive: a policy file can only ever make a project stricter. | | `ApprovalRequirement` / `ApprovalGrant` | An outstanding demand, and a decision actually given. A grant is bound to an exact `plan_hash` (and `commit_sha` for `change`): change the plan and its grants stop applying. An approval of "publish these 12 posts" must not carry over to a plan that publishes 400. | | `ExecutionPlan` | An operation fully described before it runs: steps, union scope, risk, estimate, rollback, and the repository state it assumes. `ExecutionEstimate` meters cost before it is priced — `tokens`, `duration_ms`, `items`, `bytes_stored` (at rest) and `bytes_out` (moved); storage and egress are separate because they are billed by different rates against different quantities. | | `ExecutionReceipt` | What happened: status, approvals, checkpoints, verification results, measured cost, and the scope actually touched — the same `ExecutionScope` shape as the plan, so prediction and outcome can be subtracted. Release approvers are the `approvals` entries with `gate: 'release'`; read them with `approversFor()`. | | `DeploymentTarget` | Where a build is published. Carries a `secret_ref`, never a secret — this document is written to git. | | `AutomationDefinition` | Reserved shape for `.contentrain/automations.json`. Nothing reads it yet; it exists so the first writer does not invent a fourth vocabulary for schedules. | | `SourceDeltaPlan` | The WordPress→repo delta — *not* `contentrain_reconcile`, which merges two git branches and knows nothing about WordPress. Carries explicit deletion tombstones, because `modified_after` is a filter on changed records and never reports a deletion, plus slug moves (which generate redirects) and semantic conflicts. `deletions_detectable: false` must not be read as "nothing was deleted". | | `SourceInventory` / `SourceInventoryRecord` | Every origin record in scope at one moment — what a `bridge_inventory` cursor's hash identifies. Deletions and moves are proven by comparing two inventories (records keyed by `wp_type` + `wp_id`, updates decided on `fingerprint`); `modified_after` only narrows what to fetch again. `SourceDeltaEntry` also carries `path_before`/`path_after` for moves a slug cannot express, and `deleted_kind` (`trashed` / `purged`). | ### The evaluator `approval.ts` is the decision procedure over these shapes: given a plan, a policy and the decisions collected so far, may this proceed? ```ts import { evaluateApproval, requiredApprovals } from '@contentrain/types' // For the plan card, before anyone has decided: requiredApprovals(plan, policy) // → [{ gate: 'release', mode: 'quorum', min_approvals: 2, because: 'deployment' }] // At the gate: const decision = evaluateApproval({ plan, policy, grants, commit_sha, now }) decision.allowed // every requirement met and the plan has not expired decision.outstanding // what is still missing, with who has signed so far decision.rejected_grants // decisions that did not count, each with a reason decision.reasons // one line per blocker, written for a person ``` It replaces a role check. Studio's `shouldAutoMerge` asks "is this person an owner?", which cannot express "a bulk publish needs a second pair of eyes even from the owner" and cannot tell a typo fix from a domain cutover. This asks about the action: its risk, its scope, and what the project's policy says about that combination. Rules that matter: - **A plan cannot understate itself.** `effectiveRisk()` takes the worst of the plan's declared class and its steps', so a plan labelled `read_only` that carries a deploy step is evaluated as a deploy. - **Each matching rule is its own requirement and all must be met.** Merging two rules would need a way to combine their modes, roles and counts, and every such rule has a case where the result is *looser* than one of its inputs. - **`auto` does not climb the ladder.** Every other mode covers its class and everything above it. If `auto` did too, one `auto` rule on a low rung would exempt every heavier operation above it — the one mode that demands nothing would become the only mode that can loosen a policy. - **An agent never approves.** Not its own work, not anyone's. The author of a plan cannot approve it either unless the project sets `allow_self_approval`, and that setting does not extend to agents. - **A `change` decision is a decision about a diff.** Presented with a different branch tip than the one reviewed, it does not count. - **`now` is an input.** Nothing reads the clock, so a blocked run can be explained months later by replaying the same arguments. Every rejected decision carries a machine-readable reason (`plan_hash_mismatch`, `commit_mismatch`, `expired`, `agent_approver`, `self_approval`, `role_not_permitted`, `duplicate_approver`, `no_matching_requirement`), because the useful question is never "is it blocked" but "I approved this, why is it still blocked". With no `.contentrain/approval-policies.json`, `DEFAULT_APPROVAL_POLICY` applies: read-only work proceeds, everything else wants one reviewer on the diff. Whether a project consults the evaluator at all is still governed by its `workflow` setting. ### `plan_hash` `computePlanHash(plan)` is SHA-256 over `planHashPayload(plan)`: canonical JSON (sorted keys, 2-space indent, trailing newline) of the plan's semantic fields. Excluded from the payload: `plan_hash` itself, and `id`, `created_at`, `created_by`, `idempotency_key` — who built a plan, when, under which run id and with which deduplication key do not change what the plan will do, and regenerating the same operation must produce the same hash or idempotency and approval binding both break. Everything else is covered, so a widened scope, an added step, a raised estimate or a withdrawn rollback each invalidate every approval the plan had collected. It is async because it uses Web Crypto (`crypto.subtle`), available in Node 18+, Deno, Bun, workers and browsers alike — this package is consumed in all of them and must not reach for `node:crypto`. A non-cryptographic hash was rejected: approvals are pinned to this value, so a collision is an approval bypass. The digest is reproducible from the contract alone — the test suite pins a golden hash cross-checked against an independent canonical-JSON + SHA-256 implementation in another language. ### Reserved paths `RESERVED_PATHS` names four files under `.contentrain/` that this repository has claimed but does not yet write: `capabilities.json`, `automations.json`, `approval-policies.json`, `redirects.json`. `.contentrain/` is a shared namespace — Studio, the migration engine and a customer's own tooling all write into it — so a name claimed here cannot later be taken for something else, and the tools that walk the directory know these four are expected rather than stray. Until a tool owns one, the contract is narrow and pinned by tests in `@contentrain/mcp`: - `contentrain_doctor` and `contentrain_validate` ignore them completely. They are not orphans, not broken content, and not the validator's business. - `contentrain_reconcile` treats each as one opaque file: it takes the side that changed it, and reports `file_conflict` when both sides did. It never merges their interiors, because it does not know their interiors — a field-level union on an approval policy would produce a policy nobody wrote. ## Comments export by repository path `MigrationHandoff.comments.export` (`HandoffCommentsExport`) says where the full comments export (`contentrain-comments@1`) is. A producer writes at most one of: | Field | When | |---|---| | `path` | Large exports: a file in the generated repository. The consumer reads it at the same commit SHA it read the handoff from (not a branch name, which can move between the two reads), with the repository access it already has, so a private repository needs no public URL | | `url` | A file fetched over http(s) | | `inline` | Small exports, embedded in the handoff | With none of them, the export exists but has no reference yet (a large export with no repository to put it in): a valid state with nothing to import. The file at `path` or `url` is the export as UTF-8 JSON. `bytes` (size) and `sha256` (lowercase hex) are taken over its raw bytes as stored, so a consumer can refuse an oversized export before reading it and check what it read. `path` is a POSIX path relative to the repository root, in one normal form: no leading `/` or `./`, no `.`, `..`, `.git` or empty segment, no backslash, no scheme or drive, no control character, Unicode in NFC. `isRepoRelativePath()` is that check, so a path can never leave the repository or reach its git internals, and no two producers spell one file two ways. A consumer reading a local checkout also checks that the file is not a symlink (`lstat`) before reading it. ```ts import { commentsExportSource, validateHandoffCommentsExport } from '@contentrain/types' const source = commentsExportSource(handoff.comments?.export) // { kind: 'path', path } | { kind: 'url', url } | { kind: 'inline', export } | undefined ``` `commentsExportSource()` reads `path` first, then `url`, then `inline`, and skips a `path` that is not in normal form and a `url` that is not http(s). `validateHandoffCommentsExport()` returns `{ errors, warnings }` for a producer's own check or a consumer's report: errors for several sources or a bad path, url, size or hash; warnings when a file at `path` or `url` comes without `sha256` or `bytes`. ## Migrate → Studio claim A paid Migrate order includes a Studio trial. At delivery, Migrate hands the customer to Studio with a signed claim token: a compact JWS, `alg: "EdDSA"` (Ed25519), signed with Migrate's private key and verified with its public key (no shared secret; optional `kid` for rotation). `MigrateStudioClaim` is the payload both apps bind to. | Claim | Meaning | |---|---| | `iss` / `aud` | `contentrain-migrate` / `contentrain-studio` | | `sub` | Migrate account id | | `jti`, `iat`, `exp` | single-use id; `exp − iat ≤ 1800` s | | `v` | contract version (`1`) | | `order_id` | Migrate order; Studio grants once per order | | `email` | verified at Migrate; shown, not required to match the GitHub login | | `plan`, `plan_evidence` | `starter` \| `pro`, and the measurements it was sized on (`limit_key`, `measured`, `limit`, optional `capability`) | | `trial_days` | 1..90 (v1: 60), never taken from the client | | `repo` | `{ provider: 'github', owner, name }` of the delivered site | | `capabilities` | optional discovery summary for the claim screen | | `origin` | optional migrated site as a bare origin (`https://host`; `http:` only for localhost). Studio stores it on the grant and fetches migrated media from it alone | | `comments_export` | optional `{ url, token, expires_at, comments }`: Migrate's fixed address for the order's comment export (PII removed), fetched with `token` (a per-job signed JWS) as `Authorization: Bearer`, valid until `expires_at` (end of the grant window; missing, invalid or expired → 404). The address carries no secret. The export never enters the repository. Studio fetches it server-side only, from hosts on its own Migrate allowlist | ```ts import { validateMigrateStudioClaim } from '@contentrain/types' // after verifying the JWS signature: const result = validateMigrateStudioClaim(payload, { now: Math.floor(Date.now() / 1000) }) if (!result.ok) throw new Error(result.errors.join('; ')) ``` `validateMigrateStudioClaim` checks shape, ranges and — with `now` — the validity window (60 s skew). It does no cryptography: the signature, `jti` replay and `order_id` uniqueness are the consumer's job. `isMigrateStudioClaim` is the shape-only type guard. A malformed `comments_export` does not fail the claim: it is dropped from `result.claim` and reported in `result.warnings` (`comments_export.*: …`), and the trial opens without the export. The guard is stricter: it returns `false` for such a claim, since it narrows the input itself, malformed export included. Read `result.claim` instead. **Claim v2 ("Migrate with Studio").** `MigrateStudioClaimV2` (`v: 2`, `validateMigrateStudioClaimV2`, or `validateMigrateStudioClaimAny` to route by `v`) carries no `trial_days`: the Studio year is part of the order's first invoice, and Studio creates that checkout itself, server to server. It adds `github_user_id` (decimal string, from the Migrate sign-in), `email_verified` (Studio binds by email only when true), `return_url` and a signed `billing` quote (`migrate_fee_cents`, `quoted_total_cents`, `currency: 'usd'`) that Studio checks against its own Studio-year price before opening the checkout. The Offer-time exchange is `MigrateAccountStateRequest` / `MigrateAccountStateResponse` (`state: none | covers | too_small`, `year1_cents`). The request's `github_user_id` is optional: without it (before sign-in) the Offer asks for the sized plan's list price, and Studio answers `none`. Studio checks the request with `validateMigrateAccountStateRequest` and keeps a `jti` replay record for it, as for claims; Migrate checks the answer with `validateMigrateAccountStateResponse(response, { requested })` (`requested` is required: an answer is only checked against its question), which requires `plan` to be the requested plan for `none` / `too_small`, `current_plan` below it for `too_small`, at least it for `covers`, and no `current_plan` for `none`. v1 and `validateMigrateStudioClaim` are unchanged. **Who collects the bundle.** `billing.collector` says who takes the one payment. - **`studio_polar`** (or absent): Studio opens the bundle's Polar checkout (`MigrateProvisionCheckout`). - **`migrate`**: Studio opens no checkout. It answers `MigrateProvisionReserved`, the Studio line it reserved: `amount_cents` = `quoted_total_cents − migrate_fee_cents`. - Migrate charges the whole bundle in its own checkout. - Once paid, Migrate reports the payment with `MigrateGrantActivateRequest` (`POST /api/migrate/grants/activate`: provider, `transaction_id`, `paid_at`, `studio_amount_cents`). - Studio starts a prepaid Studio year with no subscription, from `paid_at` for `MIGRATE_PREPAID_YEAR_SECONDS`. - The year does not renew by itself. The grant status answers `renewal: none | scheduled`, the latter once the customer has set up their own subscription to follow it. `validateMigrateProvisionResponse(response, { quoted_total_cents, collector, migrate_fee_cents })` accepts only the answer the collector asked for. An older Studio's Polar checkout is refused when Migrate collects (fail closed). `validateMigrateGrantActivateResponse(response, { paid_at })` requires the year to start at `paid_at` and last exactly one prepaid year, because the refund's pro-rata days rest on both. The revoke reason `studio_not_delivered` covers a Studio year Migrate collected but Studio could not start; Studio's share alone is refunded. ## Project plan `ProjectPlan` (`contentrain-project-plan@1`) is the one holistic decision of a Migrate v3 migration. It sits between the fact pack (what the WordPress site is) and the writer (the Astro + Contentrain project). Content is **bound, never copied**: a plan names fields, and the engine applies it to every entry. | Part | Holds | |---|---| | `site` | the starter's `site.config.ts` (permalinks, home, postsPerPage, menu slugs, studio), plus `url`, `redirects` and `tokens` (the kit's `@theme` roles, extra scale, WordPress presets, self-hosted fonts); a multilingual site's `locales` (`default`, `supported`, and per content locale code its address `prefixes` and BCP 47 `tags`) | | `layout` | header and footer placements shared by every route | | `models` | `import` models (wp-import's ids) are referenced; `plan` models carry `name`, `domain`, `i18n`, `title_field`, `fields` and `extract` rules (builder element → entry → `\|` field paths) | | `components` | `kit` (catalog id; the kit's copy planner places it under `src/components/kit//`) or `site` (props + a brief for the writer) | | `routes` | pattern, fact template, `source` (one page per entry), `body` `rich-text` \| `composed`, and placements; `locale` when a route builds a non-default locale's pages | | `decisions` | who answered what (rule, cache, jew, haiku, sonnet, opus, fallback, human) | A placement binds props with a small closed value set: `field:`, `media:` (the kit's `ImageInput`), `ref:.`, `href:self` / `href:`, `term:` (`{ label, href }`), `ui:`, `site:`, `menu:primary|footer`, `page:base|current|total|breadcrumb`, `const:`: the builder mapping tables' set without the element expressions. An extraction may name a mapping `rule` to fill a plan model entry from an element. It also takes `labels` (prop → `ui-strings` key). A collection binding with `into` fills one array prop (`card-grid.items`); without it, the component repeats per entry. `validateProjectPlan(plan)` returns `{ errors, warnings }`. It checks that every reference resolves, that permalinks and values are well formed, that required props are bound, that plan models are valid Contentrain models (a text-like `title_field`), and that routes over one model give each entry exactly one address. With `site.locales`, the default is supported and equals `site.locale`, every supported code (`LOCALE_PATTERN`) has one prefix and one tag, only the default locale is served at the root and no two share a prefix; a route's `locale` is a site locale. `CSS_LENGTH` is the CSS size it accepts, exported for a plan's producer. Kit catalog and fact checks belong to the caller. ## Understand contract Migrate's render-first pipeline, "AI understands, the engine executes", binds three stages to one file (`understand.ts`): | Stage | Output | Made by | |---|---|---| | facts | `Band[]`: horizontal bands of a template's page, cut by geometry, each with its box per width, its node range and a `MeasuredStyle` | measurement, no model | | understand | `RegionSpec[]`: what each band is (`Archetype`, confidence) and which outline nodes hold its content (`slots`) | one model reading per template | | plan | placements: archetype → kit component, measured values as parameters by `Fidelity` | deterministic | The contract names no source system and no target framework. What a source knows beyond the render travels in `Band.hints`, and nothing may depend on it. What the capture itself did to a band (a slider held at its first slide, a lazy background loaded) is a typed fact, `Band.settled`, because a gate reads it to tell a loss of state from a loss of design. **A region spec holds node ids, never content.** A `SlotRef` is `{ node, background? }`, where `node` is the pre-order index of the element in the template's outline at 1280 px (root = 0). Text, image addresses, link targets and icons are read from that node by the engine. The model returns no colour, size or layout value either: those are measured. The slot vocabulary is closed and exported as data (`REGION_SLOT_DEFS`, `REGION_ITEM_SLOT_DEFS`, `REGION_GROUP_SLOT_DEFS`: slot name → kind and one-or-list), so a prompt, a schema and the validator read the same table. An item's `text` is asked as one ref but also takes a list of the item's blocks in order (`list: true`): the engine folds a card's further paragraphs in. ```ts import { needsFallback, validateBands, validateRegionSpecs, type Band, type RegionSpec } from '@contentrain/types' declare const bands: Band[] declare const answered: RegionSpec[] declare function nodeHolds(node: number, kind: 'text' | 'image' | 'link' | 'icon', background: boolean): boolean validateBands(bands) // [] when ids are unique and node ranges do not overlap const issues = validateRegionSpecs(answered, bands, { // The outline lives with the engine: it says whether a node holds what the slot's kind needs. resolves: (ref, kind) => nodeHolds(ref.node, kind, ref.background === true), }) const rejected = new Set(issues.map(issue => `${issue.band}#${issue.part}`)) const specs = answered.filter(spec => !rejected.has(`${spec.band}#${spec.part}`)) const fallback = specs.filter(needsFallback) // 'other' or confidence < 0.5 → the styled fallback section ``` `validateRegionSpecs` rejects, with a code and a slot path each: an unknown band or archetype, a slot outside the vocabulary, a ref outside its band's node range, a node that holds nothing of the slot's kind (`slot_unresolved`), a `background` on a non-image slot, an item archetype without items, and a `sameAs` or `continues` that does not point where it may (`continues` joins a band to an earlier region of the same archetype, or to the `text` introduction above it: one section, list slots joined in band order, the earlier region's ref kept where both hold the same single slot). A rejected region is recorded in `UnderstandRun.issues` and never reaches the plan; a band left without a region is built as the styled fallback section. `UnderstandRun` also carries the ledger: one `UnderstandCall` per reading with its `promptHash` (the key a stored response is replayed by), token counts, cost and whether it was replayed. ## Frontmatter round trip A document's fields live in YAML frontmatter, and two readers open them: the content engine, through `parseMarkdownFrontmatter` (which `@contentrain/mcp` re-exports), and `@contentrain/query`'s client generator and Astro loader. The property both depend on is that a value written and read back is the same value — and for six shapes it did not hold. | Value | Came back as | |---|---| | `He said "Hi"` | `He said \"Hi\"` — the quotes were stripped without decoding the escapes | | `C:\path\to` | `C:\\path\\to` — and doubling again on every further save | | `line one`⏎`line two` | `line one` — the rest was written as frontmatter lines the reader then skipped | | ` padded ` | `padded` | | `'42'` (a string) | `42` (a number) | | `true` (a boolean) | `'true'` (a string) | All six are fixed, and the guarantee is now explicit: **for every value `serializeMarkdownFrontmatter` can write, `parseMarkdownFrontmatter` returns it unchanged, and a second round trip produces identical bytes.** The second trip is part of the test on purpose — backslash doubling only diverges on the trip after the one that introduced it, so a single-trip test passes on content that corrupts a little more with every export. What that required: - A quoted scalar's escapes are decoded (`\\`, `\"`, `\n`, `\r`, `\t`, `\uXXXX`). An unrecognised escape keeps its backslash rather than erroring — hand-written frontmatter says `"C:\Users"`, and losing that to strictness is a worse trade than keeping the bytes. Text that merely starts and ends with a quote (`"a" and "b"`) is not treated as one scalar, because slicing its ends off would corrupt it. - A value carrying a newline, tab, backslash or edge whitespace is quoted and escaped, so it occupies one line and no part of it is silently dropped. - A **string** that would read back as another type is quoted; a real boolean, number or null is not, so each reads back as itself. - An empty array is written `key: []`. A bare `key:` is genuinely ambiguous — empty array, empty object, or null — and the two readers were guessing it differently. The scalar grammar is exported (`parseFrontmatterScalar`, `parseFrontmatterScalarString`, `splitFrontmatterList`) and imported by the SDK reader rather than replicated. That is the actual fix: when each side had its own copy, correcting one of them would have turned a shared bug into a silent disagreement between the generated client and the content engine. A parity suite in `@contentrain/query` asserts both readers return the same values for the same bytes. Body text keeps its internal blank lines; only its leading and trailing whitespace is normalised, which is markdown behaviour rather than loss.