rvlib-shipkit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 — 2026-07-22
+
+- contracts: manifest data language (`file/png/glob/md/dir/custom` rules,
+  `script/fileContains/dirExists` detectors, loud `defineContract`) + engine:
+  both-ways drift (declared-incomplete FAILs, undeclared-but-detected FAILs),
+  IHDR png dimension checks, `public-surface` gate (WARN before a surface),
+  visible `exempt` skips, one fix pointer per contract per severity. Five
+  generic venue manifests bundled (itch, steam, social, discord, identity).
+- core: v0 wire protocol (`ok:/WARN/FAIL:/skip:/fix:` — FROZEN), CheckCtx
+  (guarded fetch/exec), CheckSuite (TTL cache, secret-rotation busting,
+  injectable secret backend), task runner (dep DAG with race-guard edges,
+  per-task logs + timeout escalation, kill-on-bail/interrupt, group/only/
+  opt-in filters, loud cycle detection).
+- asks: per-repo human queue — list/new/check/archive, numbered files never
+  reused, frozen stdout prefixes (`closed + archived` / `archived` / `still`).
+- wiki: md-wiki link-graph server + orphan/dangling lint (folded in from
+  rvlib-mdwiki 0.2.0, now frozen on npm).
+- `defineRepo` (repo.config.ts) with auto-registered floor tasks + `shipkit`
+  CLI: `ci · check · contracts · asks/ask · wiki · init`.

package/README.md

@@ -0,0 +1,58 @@
+# rvlib-shipkit
+
+Repo toolkit for shipping: one config file gives a repo a commit gate
+(task DAG), release-contract fulfillness checks, a human ask queue, and
+markdown-wiki tooling.
+
+```sh
+bun add -d rvlib-shipkit
+bunx rvlib-shipkit init     # scaffolds repo.config.ts + package.json scripts
+```
+
+```ts
+// repo.config.ts
+import { defineRepo } from 'rvlib-shipkit'
+
+export default defineRepo({
+    name: 'my-game',
+    venues: ['itch'],          // which release contracts are REQUIRED
+    social: ['x', 'discord'],  // .rv-social/<channel>/ post folders (+ .rv-discord/)
+    tasks: [{ id: 'typecheck', cmd: ['bun', 'run', 'typecheck'], deps: ['lint'] }],
+})
+```
+
+## CLI
+
+```
+shipkit ci        commit gate: auto-registered floor (lint/typecheck/test/…)
+                  + contracts + your tasks, parallel DAG   [--bail --skip g --only id --json]
+shipkit contracts release-contract fulfillness alone       [--venue v --json]
+shipkit check     periodic health checks, TTL-cached       [--json --fresh]
+shipkit asks      human action queue: list · ask "<title>" · asks check (auto-close)
+shipkit wiki      serve|lint — live md link-graph + orphan/dangling-ref lint
+shipkit init      scaffold config + scripts
+```
+
+Output is a stable line protocol — `ok:` / `WARN` / `FAIL:` / `skip:` with
+indented `fix:` pointers — exit 0/1. Greppable by humans, parseable by
+agents, `--json` where structure helps.
+
+## Release contracts
+
+A venue contract is data: required files, exact PNG dimensions (header-parsed,
+no image dependency), glob minimums, required markdown sections. Enforcement
+is both ways — a declared venue with an incomplete folder fails, and an
+undeclared venue whose signals fire (deploy scripts, folders) fails too.
+`exempt: { steam: "reason" }` skips visibly. Wire venue deploys as
+`deps: ['contracts']` and an incomplete folder physically blocks the upload.
+
+Ship your own contracts via `contracts: { extra: [defineContract({...})] }`
+— see `rvlib-shipkit/contracts` for the rule vocabulary.
+
+## Library use
+
+Everything the CLI does is importable: `runTasks`, `CheckSuite`,
+`evaluateContracts`, the asks queue, `scanMdGraph`/`lintMd`/`serveMdGraph`.
+Ships TypeScript source; Bun ≥ 1.0.
+
+MIT

package/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "rvlib-shipkit",
+    "version": "0.1.0",
+    "description": "Repo toolkit: task runner, release-contract fulfillness checker, asks queue, md-wiki tools",
+    "license": "MIT",
+    "type": "module",
+    "files": ["src", "README.md", "CHANGELOG.md"],
+    "bin": {
+    "shipkit": "./src/cli.ts"
+},
+"exports": {
+    ".": "./src/shipkit.ts",
+    "./contracts": "./src/contracts/contract-types.ts",
+    "./src/*": "./src/*"
+},
+"devDependencies": {
+    "@types/bun": "^1.3.14"
+}
+}

package/src/asks/asks-queue.ts

@@ -0,0 +1,95 @@
+// Persistent human<->agent queue for real-world actions and answers.
+// One md file per ask in <dir>/, git-tracked; <dir>/done/ archive. The agent
+// greps status; the human edits files (or just does the thing — check()
+// auto-closes asks whose `check:` probe passes).
+//
+// Stdout contract (FROZEN — consumers parse the prefixes): `closed +
+// archived <file>` / `archived <file>` / `still <status> <file>` / `N closed`.
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+export type Ask = { file: string; status: string; kind: string; created: string; blocks: string; check: string | null; title: string }
+export type CreateOpts = { kind?: string; blocks?: string; check?: string }
+
+const parse = (dir: string, file: string): Ask => {
+    const md = readFileSync(join(dir, file), 'utf8')
+    const fm = (key: string): string | null => md.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim() ?? null
+    return {
+        file,
+        status: fm('status') ?? 'open',
+        kind: fm('kind') ?? 'action',
+        created: fm('created') ?? '?',
+        blocks: fm('blocks') ?? '-',
+        check: fm('check'),
+        title: md.match(/^# (.+)$/m)?.[1] ?? file,
+    }
+}
+
+export function listAsks(dir: string): Ask[] {
+    mkdirSync(dir, { recursive: true })
+    return readdirSync(dir).filter((f) => f.endsWith('.md')).sort().map((f) => parse(dir, f))
+}
+
+export function openAsks(dir: string): Ask[] {
+    return listAsks(dir).filter((a) => a.status !== 'done')
+}
+
+export function checkAsks(dir: string, print: (line: string) => void = console.log): { closed: number } {
+    const done = join(dir, 'done')
+    mkdirSync(done, { recursive: true })
+    let closed = 0
+    for (const a of listAsks(dir)) {
+        if (a.status === 'done') { renameSync(join(dir, a.file), join(done, a.file)); print(`archived ${a.file} → done/`); continue }
+        if (a.check == null) { print(`still ${a.status.padEnd(8)} ${a.file} (manual — no probe)`); continue }
+        const p = Bun.spawnSync(['bash', '-lc', a.check])
+        if (p.exitCode === 0) {
+            const md = readFileSync(join(dir, a.file), 'utf8').replace(/^status:.*$/m, `status: done\nclosed: ${new Date().toISOString().slice(0, 10)}`)
+            writeFileSync(join(dir, a.file), md)
+            renameSync(join(dir, a.file), join(done, a.file))
+            print(`closed + archived ${a.file}`)
+            closed++
+        } else {
+            print(`still ${a.status.padEnd(8)} ${a.file}`)
+        }
+    }
+    print(`${closed} closed`)
+    return { closed }
+}
+
+export function createAsk(dir: string, title: string, opts?: CreateOpts): string {
+    mkdirSync(dir, { recursive: true })
+    // max numeric prefix across BOTH live and archived asks — numbers are never reused
+    const done = join(dir, 'done')
+    const archived = existsSync(done) ? readdirSync(done).filter((f) => f.endsWith('.md')) : []
+    const n = Math.max(0, ...[...listAsks(dir).map((a) => a.file), ...archived].map((f) => parseInt(f, 10) || 0)) + 1
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40)
+    const file = `${String(n).padStart(3, '0')}-${slug}.md`
+    if (existsSync(join(dir, file))) throw new Error(`refusing to overwrite existing ${file}`)
+    const check = opts?.check ?? null
+    writeFileSync(join(dir, file), `---
+status: open
+kind: ${opts?.kind ?? 'action'}
+created: ${new Date().toISOString().slice(0, 10)}
+blocks: ${opts?.blocks ?? '-'}${check != null ? `\ncheck: ${check}` : ''}
+---
+
+# ${title}
+
+**Ask**: ${title}
+
+**Why**: TODO
+
+**Answer**: _(fill in / check off, or just do it — the check probe auto-closes when it passes)_
+
+**Done when**: ${check != null ? `\`${check}\` exits 0` : 'status flipped to done'}
+`)
+    return file
+}
+
+export function renderAsksTable(dir: string, print: (line: string) => void = console.log): number {
+    const open = openAsks(dir)
+    if (open.length === 0) { print('no open asks — all caught up 🎉'); return 0 }
+    for (const a of open) print(`${a.status.padEnd(9)} ${a.kind.padEnd(7)} ${a.file.padEnd(44)} blocks: ${a.blocks}`)
+    print(`\n${open.length} open — details: ${dir}/<file>`)
+    return open.length
+}

package/src/cli/shipkit-asks.ts

@@ -0,0 +1,26 @@
+// shipkit asks — the per-repo human queue. `asks` lists, `asks check`
+// probes + archives, `ask "<title>"` (dispatch rewrites to `asks new`).
+import { join } from 'path'
+import { checkAsks, createAsk, renderAsksTable } from '../asks/asks-queue.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+
+const flagVal = (args: string[], name: string): string | undefined => {
+    const i = args.indexOf(`--${name}`)
+    return i !== -1 ? args[i + 1] : undefined
+}
+
+export async function main(args: string[]): Promise<number> {
+    const root = process.cwd()
+    const dir = join(root, (await loadRepoConfig(root)).asks?.dir ?? 'asks')
+    const sub = args[0]
+    if (sub === 'check') { checkAsks(dir); return 0 }
+    if (sub === 'new') {
+        const title = args[1]
+        if (title == null || title === '') { console.error('usage: shipkit ask "<title>" [--kind action|info] [--blocks <what>] [--check "<cmd>"]'); return 2 }
+        const file = createAsk(dir, title, { kind: flagVal(args, 'kind'), blocks: flagVal(args, 'blocks'), check: flagVal(args, 'check') })
+        console.log(`created ${dir}/${file}`)
+        return 0
+    }
+    renderAsksTable(dir)
+    return 0
+}

package/src/cli/shipkit-check.ts

@@ -0,0 +1,26 @@
+// shipkit check — periodic health: contracts + the repo's TTL'd checks.
+// Clean passes replay from cache; SHIPKIT_FRESH=1 (or --fresh) busts.
+import { join } from 'path'
+import { CheckSuite } from '../core/check-suite.ts'
+import { activeContracts, applyContractsResult, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
+import { evaluateContracts } from '../contracts/contracts-engine.ts'
+
+export async function main(args: string[]): Promise<number> {
+    const root = process.cwd()
+    const c = await loadRepoConfig(root)
+    if (args.includes('--fresh')) process.env.SHIPKIT_FRESH = '1'
+    const suite = new CheckSuite({ name: c.name, cacheDir: join(root, 'tmp/.shipkit-cache') })
+    suite.addCheck({
+        name: 'contracts',
+        logic: async (t) => {
+            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)))
+        },
+    })
+    for (const chk of c.checks ?? []) suite.addCheck({ name: chk.id, remainValidFor: chk.remainValidFor, version: chk.version, logic: chk.logic })
+    const r = await suite.execute()
+    if (args.includes('--json')) { console.log(JSON.stringify(r)); return r.exitCode }
+    const { formatLine } = await import('../core/wire.ts')
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+    for (const l of r.lines) console.log(formatLine(l, color))
+    return r.exitCode
+}

package/src/cli/shipkit-ci.ts

@@ -0,0 +1,30 @@
+// shipkit ci — the commit/deploy gate: floor + contracts + repo tasks
+// through the DAG runner. Exit 0/1; --json prints the structured summary.
+import { join } from 'path'
+import { allTasks, loadRepoConfig } from '../repo-config.ts'
+import { runTasks } from '../core/task-runner.ts'
+
+const flagVals = (args: string[], name: string): string[] => {
+    const out: string[] = []
+    for (let i = 0; i < args.length; i++) if (args[i] === name && args[i + 1] != null) out.push(args[i + 1]!)
+    return out
+}
+
+export async function main(args: string[]): Promise<number> {
+    const root = process.cwd()
+    const c = await loadRepoConfig(root)
+    const { tasks, disabled } = allTasks(c, root)
+    for (const d of disabled) console.log(`skip: ${d} (skipped-by-config)`)
+    const summary = await runTasks({
+        tasks,
+        logDir: c.logDir ?? join(root, 'tmp/shipkit-ci'),
+        cwd: root,
+        bail: args.includes('--bail'),
+        skipGroups: flagVals(args, '--skip'),
+        withIds: flagVals(args, '--with'),
+        onlyIds: flagVals(args, '--only'),
+    })
+    if (args.includes('--json'))
+        console.log(JSON.stringify({ ok: summary.ok, interrupted: summary.interrupted, disabled, tasks: summary.results.map((r) => ({ ...r, lines: undefined })) }))
+    return summary.ok ? 0 : 1
+}

package/src/cli/shipkit-contracts.ts

@@ -0,0 +1,26 @@
+// shipkit contracts — fulfillness alone, fast and filesystem-only.
+// Venue deploy scripts call this before any upload.
+import { activeContracts, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
+import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { formatLine } from '../core/wire.ts'
+
+export async function main(args: string[]): Promise<number> {
+    const root = process.cwd()
+    const c = await loadRepoConfig(root)
+    const venueIdx = args.indexOf('--venue')
+    const only = venueIdx !== -1 ? args[venueIdx + 1] : null
+    let manifests = activeContracts(c)
+    if (only != null) {
+        manifests = manifests.filter((m) => m.venue === only)
+        if (manifests.length === 0) { console.error(`FAIL: unknown venue '${only}'`); return 1 }
+    }
+    const r = await evaluateContracts(manifests, contractsConfigFrom(c, root))
+    if (args.includes('--json')) {
+        console.log(JSON.stringify({ ok: r.exitCode === 0, outcomes: r.outcomes }))
+        return r.exitCode
+    }
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+    for (const l of r.lines) console.log(formatLine(l, color))
+    if (r.lines.length === 0) console.log('ok: no contracts apply (nothing declared, nothing detected)')
+    return r.exitCode
+}

package/src/cli/shipkit-init.ts

@@ -0,0 +1,40 @@
+// shipkit init — scaffold repo.config.ts + package.json scripts. Refuses to
+// overwrite an existing config; script merge never clobbers existing keys.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+const CONFIG_TEMPLATE = (name: string): string => `import { defineRepo } from 'rvlib-shipkit'
+
+export default defineRepo({
+    name: '${name}',
+    venues: [], // e.g. ['itch', 'steam'] — selects which .rv-<venue>/ contracts are REQUIRED
+    social: [], // e.g. ['x', 'discord'] — .rv-social/<channel>/ post folders (+ .rv-discord/)
+    tasks: [],  // repo commit-gate tasks; deps double as race guards
+    checks: [], // periodic health, TTL-cached
+})
+`
+
+export async function main(_args: string[]): Promise<number> {
+    const root = process.cwd()
+    const configPath = join(root, 'repo.config.ts')
+    if (existsSync(configPath)) { console.log(`skip: repo.config.ts already exists`); return 0 }
+    const pkgPath = join(root, 'package.json')
+    if (!existsSync(pkgPath)) { console.error('FAIL: no package.json here — run from the repo root'); return 1 }
+    const pkgRaw = readFileSync(pkgPath, 'utf8')
+    const pkg = JSON.parse(pkgRaw) as { name?: string; scripts?: Record<string, string> }
+    writeFileSync(configPath, CONFIG_TEMPLATE(pkg.name ?? 'my-repo'))
+    console.log('ok: repo.config.ts created')
+    const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '
+    pkg.scripts ??= {}
+    let added = 0
+    for (const [k, v] of [['ci', 'shipkit ci'], ['check', 'shipkit check'], ['contracts', 'shipkit contracts']] as const) {
+        if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
+        else if (pkg.scripts[k] !== v) console.log(`skip: package.json script '${k}' exists — left untouched`)
+    }
+    if (added > 0) {
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
+        console.log(`ok: ${added} package.json script(s) added`)
+    }
+    console.log('next: fill venues/social in repo.config.ts, then `bun run ci`')
+    return 0
+}

package/src/cli/shipkit-wiki.ts

@@ -0,0 +1,74 @@
+// shipkit wiki — md-wiki graph server + link lint (folded in from the
+// standalone mdwiki lib; that npm package is frozen).
+//   shipkit wiki serve --root agent --port 4800 [--title t] [--index e.md] [--skip a,b]
+//   shipkit wiki lint  --root agent [--index e.md]
+import { basename, relative, resolve } from 'path'
+import { parseArgs } from 'util'
+import { lintMd } from '../wiki/lint-md.ts'
+import { scanMdGraph } from '../wiki/scan-md.ts'
+import { serveMdGraph } from '../wiki/serve-graph.ts'
+
+const USAGE = `usage: shipkit wiki <serve|lint> [--root <dir>] [--index <entry.md>] [--skip <dir,dir>]
+  serve  --port <n> (default 6161) --title <t>   live link-graph server, reload = rescan
+  lint                                           fail on orphans + dangling refs (exit 1)
+  --root defaults to cwd; default entrypoints: index.md + README.md (--index <e> = only that one)`
+
+export async function main(args: string[]): Promise<number> {
+    let parsed: ReturnType<typeof parseArgs<{ options: { root: { type: 'string'; default: string }; port: { type: 'string'; default: string }; title: { type: 'string' }; index: { type: 'string' }; skip: { type: 'string' } }; allowPositionals: true }>>
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: true,
+            options: {
+                root: { type: 'string', default: '.' },
+                port: { type: 'string', default: '6161' },
+                title: { type: 'string' },
+                index: { type: 'string' },
+                skip: { type: 'string' },
+            },
+        })
+    } catch (e) {
+        console.log(`FAIL ${e instanceof Error ? e.message : e}\n${USAGE}`)
+        return 2
+    }
+    const { values, positionals } = parsed
+    const cmd = positionals[0]
+    const root = resolve(process.cwd(), values.root)
+    const scanCfg = { root, index: values.index, skipDirs: values.skip?.split(',').filter(Boolean) }
+
+    if (cmd === 'serve') {
+        const port = Number(values.port)
+        if (!Number.isInteger(port) || port <= 0) { console.log(`FAIL --port '${values.port}' is not a port number`); return 2 }
+        const rel = relative(process.cwd(), root)
+        const title = values.title ?? (rel === '' ? basename(root) : `${basename(process.cwd())} ${rel}`)
+        try {
+            serveMdGraph({ port, title, load: () => scanMdGraph(scanCfg) })
+            console.log(`wiki graph → http://localhost:${port} (open in browser, or VSCode "Simple Browser: Show")`)
+            // keep the server alive — dispatch must not exit
+            await new Promise(() => {})
+            return 0
+        } catch (e) {
+            if (e instanceof Error && e.message.includes('in use')) {
+                console.log(`wiki graph already served → http://localhost:${port} (another window owns it)`)
+                return 0
+            }
+            throw e
+        }
+    }
+    if (cmd === 'lint') {
+        const r = lintMd(scanCfg)
+        if (r.index == null) {
+            console.log(values.index != null
+                ? `FAIL entrypoint '${values.index}' not found in ${root}`
+                : `FAIL no entrypoint: neither index.md nor README.md in ${root} — pass --index <entry.md>`)
+            return 1
+        }
+        for (const f of r.orphans) console.log(`FAIL orphan: ${f} — unreachable from ${r.index}; link it or delete it`)
+        for (const d of r.dangling) console.log(`FAIL dangling: ${d.from} → ${d.token} — target not found`)
+        if (!r.ok) { console.log(`FAIL mdwiki lint: ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s) in ${root}`); return 1 }
+        console.log(`ok mdwiki lint: ${r.files} files, all reachable from ${r.index}, no dangling refs`)
+        return 0
+    }
+    console.log(USAGE)
+    return 2
+}

package/src/cli.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+// shipkit — dispatch only; one command per file in cli/.
+const cmd = process.argv[2]
+
+const run = async (): Promise<number> => {
+    const args = process.argv.slice(3)
+    switch (cmd) {
+        case 'ci': return (await import('./cli/shipkit-ci.ts')).main(args)
+        case 'check': return (await import('./cli/shipkit-check.ts')).main(args)
+        case 'contracts': return (await import('./cli/shipkit-contracts.ts')).main(args)
+        case 'asks': return (await import('./cli/shipkit-asks.ts')).main(args)
+        case 'ask': return (await import('./cli/shipkit-asks.ts')).main(['new', ...args])
+        case 'wiki': return (await import('./cli/shipkit-wiki.ts')).main(args)
+        case 'init': return (await import('./cli/shipkit-init.ts')).main(args)
+        default:
+            console.log(`shipkit — repo toolkit
+usage: shipkit <command>
+  ci         commit gate: floor + contracts + repo tasks   [--bail --skip <group> --with <id> --only <id...> --json]
+  check      periodic health: contracts + repo checks, TTL'd  [--json --fresh]
+  contracts  contract fulfillness alone                     [--venue <v> --json]
+  asks       list open asks · asks check · ask "<title>" [--kind --blocks --check "<cmd>"]
+  wiki       serve|lint — md-wiki graph + link hygiene
+  init       scaffold repo.config.ts + package.json scripts`)
+            return 2
+    }
+}
+
+process.exit(await run())

package/src/contracts/contract-manifests.ts

@@ -0,0 +1,10 @@
+// GENERATED by contracts:sync — do not edit; sources are the co-located
+// wiki manifests. Parity is lint-enforced.
+import type { ContractManifest } from './contract-types.ts'
+import c0 from './manifests/discord.contract.ts'
+import c1 from './manifests/identity.contract.ts'
+import c2 from './manifests/itch.contract.ts'
+import c3 from './manifests/social.contract.ts'
+import c4 from './manifests/steam.contract.ts'
+
+export const allContracts: ContractManifest[] = [c0, c1, c2, c3, c4]

package/src/contracts/contract-types.ts

@@ -0,0 +1,77 @@
+// The data language `*.contract.ts` manifest files are written in: a venue
+// contract = folder + artifact rules + detectors. Evaluation engine lands in
+// ./contracts-engine.ts (0.1). All rule paths are REPO-ROOT-relative so a
+// contract can require files outside its own folder (e.g. public/og.png).
+// `warnOnly` demotes a rule to WARN — for mandates gated on a later step.
+
+export type RuleOpts = { warnOnly?: boolean }
+export type FileRule = RuleOpts & { kind: 'file'; path: string; nonEmpty: boolean }
+export type PngRule = RuleOpts & { kind: 'png'; path: string; width: number; height: number }
+export type GlobRule = RuleOpts & { kind: 'glob'; pattern: string; min: number; width?: number; height?: number }
+export type MdRule = RuleOpts & { kind: 'md'; path: string; mustContain: string[] }
+export type DirRule = RuleOpts & { kind: 'dir'; path: string }
+// probe returns FAIL messages (empty array = pass) — for rules that need the
+// repo config (declared channels) or logic the closed vocabulary can't say
+export type CustomRule = RuleOpts & { kind: 'custom'; id: string; probe: (env: ContractEnv) => string[] | Promise<string[]> }
+export type ArtifactRule = FileRule | PngRule | GlobRule | MdRule | DirRule | CustomRule
+
+// detectors: signals a repo SHIPS on a venue even when config forgot to
+// declare it — both-ways drift (config can't lie, folders can't rot).
+// Patterns are regex SOURCES (strings) so manifests stay serializable data.
+export type Detector =
+    | { kind: 'script'; pattern: string }
+    | { kind: 'fileContains'; path: string; pattern: string }
+    | { kind: 'dirExists'; path: string }
+
+export type ContractEnv = {
+    root: string
+    venues: string[]
+    social: string[]
+    exists: (relPath: string) => boolean
+}
+
+export type ContractManifest = {
+    venue: string // kebab id; the contract folder is `.rv-<venue>/`
+    dir: string
+    owner: string // docs path suffix, rendered after the consumer-configured docsBase in fix: lines
+    appliesTo: 'declared' | 'always'
+    gate?: 'public-surface' // 'always' contracts: FAIL once a public surface exists, WARN before
+    detect: Detector[]
+    artifacts: ArtifactRule[]
+}
+
+export const file = (path: string, p?: RuleOpts & { nonEmpty?: boolean }): FileRule => ({ kind: 'file', path, nonEmpty: p?.nonEmpty ?? true, warnOnly: p?.warnOnly })
+export const png = (path: string, width: number, height: number, p?: RuleOpts): PngRule => ({ kind: 'png', path, width, height, warnOnly: p?.warnOnly })
+export const glob = (pattern: string, p: RuleOpts & { min: number; width?: number; height?: number }): GlobRule => ({ kind: 'glob', pattern, min: p.min, width: p.width, height: p.height, warnOnly: p.warnOnly })
+export const md = (path: string, p?: RuleOpts & { mustContain?: string[] }): MdRule => ({ kind: 'md', path, mustContain: p?.mustContain ?? [], warnOnly: p?.warnOnly })
+export const dir = (path: string, p?: RuleOpts): DirRule => ({ kind: 'dir', path, warnOnly: p?.warnOnly })
+export const custom = (id: string, probe: CustomRule['probe'], p?: RuleOpts): CustomRule => ({ kind: 'custom', id, probe, warnOnly: p?.warnOnly })
+
+export const script = (pattern: string): Detector => ({ kind: 'script', pattern })
+export const fileContains = (path: string, pattern: string): Detector => ({ kind: 'fileContains', path, pattern })
+export const dirExists = (path: string): Detector => ({ kind: 'dirExists', path })
+
+export function validateManifest(m: ContractManifest): string[] {
+    const errs: string[] = []
+    if (!/^[a-z0-9-]+$/.test(m.venue)) errs.push(`venue '${m.venue}' must be kebab-case [a-z0-9-]`)
+    if (m.dir !== `.rv-${m.venue}`) errs.push(`dir '${m.dir}' must be '.rv-${m.venue}' (folder naming rule)`)
+    if (m.artifacts.length === 0) errs.push('artifacts must not be empty — a contract with nothing to check is prose, not a contract')
+    if (m.appliesTo === 'declared' && m.detect.length === 0) errs.push(`appliesTo 'declared' needs >=1 detector — otherwise an undeclared venue can never be caught`)
+    if (m.gate != null && m.appliesTo !== 'always') errs.push(`gate '${m.gate}' only applies to 'always' contracts`)
+    const keys = m.artifacts.map((a) => ('path' in a ? a.path : 'pattern' in a ? a.pattern : a.id))
+    const dupes = keys.filter((k, i) => keys.indexOf(k) !== i)
+    if (dupes.length > 0) errs.push(`duplicate artifact rules: ${[...new Set(dupes)].join(', ')}`)
+    for (const d of m.detect) {
+        if ('pattern' in d) {
+            try { new RegExp(d.pattern) } catch { errs.push(`detector pattern '${d.pattern}' is not a valid regex`) }
+        }
+    }
+    return errs
+}
+
+// loud gate: a broken manifest must die at import time, never mis-check quietly
+export function defineContract(m: ContractManifest): ContractManifest {
+    const errs = validateManifest(m)
+    if (errs.length > 0) throw new Error(`invalid contract '${m.venue}':\n  ${errs.join('\n  ')}`)
+    return m
+}