@mnstry/atelier 0.2.0-alpha.1

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@mnstry/atelier",
+  "version": "0.2.0-alpha.1",
+  "private": false,
+  "description": "Local-first MNSTRY Atelier workspace for agentic authoring, graph projection, and dry-run runtime readiness.",
+  "type": "module",
+  "bin": {
+    "atelier": "bin/atelier.mjs",
+    "mnstry-atelier": "bin/mnstry-atelier.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./cli": "./src/cli/run.mjs",
+    "./project": "./src/project/config.mjs",
+    "./graph": "./src/graph/graph.mjs",
+    "./projection": "./src/projection/project.mjs",
+    "./readiness": "./src/readiness/readiness.mjs",
+    "./readiness-protocols": "./src/readiness-protocols/bundled-pack.mjs",
+    "./server": "./src/server/local-sidecar.mjs",
+    "./harness": "./src/harness/context.mjs",
+    "./support": "./src/support/support-bundle.mjs",
+    "./egress": "./src/egress/forbidden-egress.mjs",
+    "./boundary": "./src/boundary/policy.mjs",
+    "./upgrade": "./src/upgrade/upgrade.mjs",
+    "./attestation": "./src/attestation/sign.mjs",
+    "./extension-packs": "./src/extension-packs/loader.mjs",
+    "./analysis/adapter": "./src/analysis/adapter.mjs",
+    "./export-contract": "./src/export/atelier-export-contract.mjs",
+    "./dry-run": "./src/validate-atelier-export-dry-run.mjs",
+    "./contracts/atelier-export.v1.schema.json": "./contracts/atelier-export.v1.schema.json",
+    "./fixtures/atelier-export/sample-studio-offer.v1.json": "./fixtures/atelier-export/sample-studio-offer.v1.json"
+  },
+  "scripts": {
+    "contract": "node src/check-atelier-export-contract.mjs",
+    "dry-run": "node src/validate-atelier-export-dry-run.mjs fixtures/atelier-export/sample-studio-offer.v1.json",
+    "test": "node --test test/*.test.mjs",
+    "syntax:check": "find bin src -name '*.mjs' -print0 | xargs -0 -n1 node --check",
+    "graph:test": "node --test test/graph.test.mjs test/graph-knowledge-graph.test.mjs test/graph-determinism.test.mjs test/graph-source-formats.test.mjs",
+    "project:test": "node --test test/project.test.mjs test/project-config.test.mjs test/projection-policy.test.mjs test/projection-alignment.test.mjs",
+    "server:security:test": "node --test test/server.test.mjs test/server-security.test.mjs test/server-proposals.test.mjs",
+    "browser:smoke": "node --test test/server.test.mjs",
+    "support-bundle:test": "node --test test/support-bundle.test.mjs test/support-egress-analysis.test.mjs",
+    "egress:check": "node bin/atelier.mjs egress check",
+    "readiness:test": "node --test test/readiness.test.mjs test/readiness-summary.test.mjs test/readiness-protocol-contract.test.mjs test/readiness-protocols.test.mjs test/readiness-protocol-runtime.test.mjs",
+    "harness:test": "node --test test/harness.test.mjs test/harness-context.test.mjs",
+    "boundary:test": "node --test test/boundary-policy-contract.test.mjs test/boundary-guard.test.mjs",
+    "upgrade:test": "node --test test/upgrade-contract.test.mjs test/upgrade.test.mjs",
+    "release:audit": "node scripts/check-release-tarball.mjs",
+    "repo:check": "node scripts/check-repo-disclosure.mjs",
+    "migrations:check": "node scripts/check-breaking-migrations.mjs",
+    "contract:compat": "node scripts/check-contract-compat.mjs",
+    "consumer:smoke": "node scripts/consumer-smoke.mjs",
+    "distribution:smoke": "node scripts/distribution-smoke.mjs",
+    "prepublishOnly": "npm run release:audit && npm run repo:check && npm run migrations:check && npm run contract:compat && npm run syntax:check && npm test && npm run consumer:smoke && npm run distribution:smoke"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MNSTRY/atelier.git"
+  },
+  "homepage": "https://mnstry.org",
+  "bugs": {
+    "url": "https://github.com/MNSTRY/atelier/issues"
+  },
+  "engines": {
+    "node": ">=22.18.0 <23"
+  },
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "TRADEMARKS.md",
+    "SECURITY.md",
+    "bin/",
+    "contracts/",
+    "fixtures/",
+    "skills/",
+    "src/",
+    "templates/",
+    "docs/",
+    "announcements/",
+    "!fixtures/projects/source-formats-workspace/content/logo.png"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "fast-uri": "3.1.5"
+  }
+}

package/skills/claude/atelier-open/SKILL.md

@@ -0,0 +1,68 @@
+# Open the Atelier
+
+Use this skill when someone says "open the atelier", "pull up the atelier",
+"show me the portal", or asks what page they are currently viewing.
+
+"Open" means **the client's native preview surface**, not the system browser.
+An Atelier is a local sidecar serving a workspace projection; the point is to
+render it where the person is already working.
+
+## Route by client
+
+| Client | How to open |
+|---|---|
+| Claude Code / Cowork | `preview_start` with the `atelier` launch config, then screenshot |
+| Codex | the harness preview pane if present, otherwise report the URL |
+| Editor with no preview pane | print the URL; do not shell out to `open` |
+
+Never use the system `open` command and never fetch the page and describe it —
+that answers a different question than the one being asked.
+
+## Starting it
+
+The workspace ships `.claude/launch.json` with `autoPort: true`. Start it by
+name (`atelier`) and use the port the harness returns. The equivalent manual
+command is:
+
+```
+./node_modules/.bin/atelier server
+```
+
+Use the local binary path. Do **not** run `npx atelier` — this package is not
+yet published to npm, and the unscoped name `atelier` belongs to an unrelated
+third-party package that `npx` would download and execute.
+
+`atelier server` resolves its port as **argv > `PORT` env > 8137**, so a
+supervisor can hand it a free port without a config edit.
+
+## Do not fight for the canonical port
+
+A workspace often keeps a long-lived instance on 8137 for humans and
+cross-service links, frequently under a supervisor that respawns it. A preview
+instance must coexist on its own port rather than evict it:
+
+- Keep `autoPort: true`. Never pin a preview instance to the canonical port.
+- "Port 8137 in use by a non-preview server" is the supervisor working, not an
+  error to clear. Start on the assigned port instead.
+- Never kill the canonical instance to pick up new code without asking — on
+  most setups it is respawned by a supervisor whose rules you may not own.
+
+## Boot time is not hang time
+
+An Atelier may build or refresh its projection at startup. While it does, the
+port is not yet open and browser calls fail with connection or policy errors
+that read like permission problems. Poll the port or `/api/health` rather than
+retrying the browser, and give a cold workspace room before declaring it broken.
+
+## Which view to open
+
+- Working inside one repo → that repo's portal, `/<repo>/index.html`
+- Workspace-level work, or "everything" → `/`
+- A repo's file audit → `/<repo>/atelier-ledger.html`
+
+## What is the user looking at?
+
+Prefer the session-aware context flow over any global "current view" file. A
+recorded current view is a hint, not authority: trust it only when a
+session-bound API response ties the view to the same workspace and a fresh
+observation. Otherwise ask for an explicit target rather than guessing.

package/skills/claude/mnstry-readiness/SKILL.md

@@ -0,0 +1,41 @@
+# MNSTRY Readiness
+
+Use this skill when preparing or reviewing MNSTRY Atelier readiness outputs for
+a tenant or project workspace.
+
+## Protocol
+
+- Use the repository's Atelier readiness protocols: `docs/tenant-readiness.md`,
+  `docs/atelier-runtime.md`, `contracts/atelier-readiness.v1.schema.json`, and
+  `contracts/atelier-claim.v1.schema.json`.
+- Treat local source, Git state, project config, repo access, boundary policy,
+  and lockfiles as review authority.
+- Treat generated graph, projection, and readiness output as evidence from the
+  current package checks, not source authority.
+- Treat model/provider output as proposed `atelier-claim@v1` records only.
+- Keep runtime identity, consent, visibility, provisioning, bookings, commerce,
+  sessions, audit, and client-grade sharing under MNSTRY runtime authority.
+
+## Output Shape
+
+Produce claim-first outputs:
+
+- Claim: the readiness statement being made.
+- Evidence: file paths, schema names, commands run, and observed behavior.
+- Authority: source, generated evidence, proposed claim, or runtime-owned.
+- Status: ready, warning, blocked, or proposed.
+- Fix path: the smallest next reviewable change.
+
+Do not introduce independent tenant semantics, new visibility terms, hidden
+provider boundaries, or runtime mutation claims. If a check cannot run, report
+the exact command, stderr, and blocker.
+
+## Safety And Hygiene
+
+- Keep package-facing output generic and placeholder-only.
+- Do not include person-specific, tenant-private, project-private, transcript,
+  support-bundle, local absolute path, agent-local state, key, token, or
+  credential material.
+- Prefer static inspection and existing defensive tests for security-sensitive
+  review work.
+- Frame checks as verifying that a control refuses, blocks, or fails closed.

package/skills/codex/atelier-open/SKILL.md

@@ -0,0 +1,68 @@
+# Open the Atelier
+
+Use this skill when someone says "open the atelier", "pull up the atelier",
+"show me the portal", or asks what page they are currently viewing.
+
+"Open" means **the client's native preview surface**, not the system browser.
+An Atelier is a local sidecar serving a workspace projection; the point is to
+render it where the person is already working.
+
+## Route by client
+
+| Client | How to open |
+|---|---|
+| Claude Code / Cowork | `preview_start` with the `atelier` launch config, then screenshot |
+| Codex | the harness preview pane if present, otherwise report the URL |
+| Editor with no preview pane | print the URL; do not shell out to `open` |
+
+Never use the system `open` command and never fetch the page and describe it —
+that answers a different question than the one being asked.
+
+## Starting it
+
+The workspace ships `.claude/launch.json` with `autoPort: true`. Start it by
+name (`atelier`) and use the port the harness returns. The equivalent manual
+command is:
+
+```
+./node_modules/.bin/atelier server
+```
+
+Use the local binary path. Do **not** run `npx atelier` — this package is not
+yet published to npm, and the unscoped name `atelier` belongs to an unrelated
+third-party package that `npx` would download and execute.
+
+`atelier server` resolves its port as **argv > `PORT` env > 8137**, so a
+supervisor can hand it a free port without a config edit.
+
+## Do not fight for the canonical port
+
+A workspace often keeps a long-lived instance on 8137 for humans and
+cross-service links, frequently under a supervisor that respawns it. A preview
+instance must coexist on its own port rather than evict it:
+
+- Keep `autoPort: true`. Never pin a preview instance to the canonical port.
+- "Port 8137 in use by a non-preview server" is the supervisor working, not an
+  error to clear. Start on the assigned port instead.
+- Never kill the canonical instance to pick up new code without asking — on
+  most setups it is respawned by a supervisor whose rules you may not own.
+
+## Boot time is not hang time
+
+An Atelier may build or refresh its projection at startup. While it does, the
+port is not yet open and browser calls fail with connection or policy errors
+that read like permission problems. Poll the port or `/api/health` rather than
+retrying the browser, and give a cold workspace room before declaring it broken.
+
+## Which view to open
+
+- Working inside one repo → that repo's portal, `/<repo>/index.html`
+- Workspace-level work, or "everything" → `/`
+- A repo's file audit → `/<repo>/atelier-ledger.html`
+
+## What is the user looking at?
+
+Prefer the session-aware context flow over any global "current view" file. A
+recorded current view is a hint, not authority: trust it only when a
+session-bound API response ties the view to the same workspace and a fresh
+observation. Otherwise ask for an explicit target rather than guessing.

package/skills/codex/mnstry-readiness/SKILL.md

@@ -0,0 +1,41 @@
+# MNSTRY Readiness
+
+Use this skill when preparing or reviewing MNSTRY Atelier readiness outputs for
+a tenant or project workspace.
+
+## Protocol
+
+- Use the repository's Atelier readiness protocols: `docs/tenant-readiness.md`,
+  `docs/atelier-runtime.md`, `contracts/atelier-readiness.v1.schema.json`, and
+  `contracts/atelier-claim.v1.schema.json`.
+- Treat local source, Git state, project config, repo access, boundary policy,
+  and lockfiles as review authority.
+- Treat generated graph, projection, and readiness output as evidence from the
+  current package checks, not source authority.
+- Treat model/provider output as proposed `atelier-claim@v1` records only.
+- Keep runtime identity, consent, visibility, provisioning, bookings, commerce,
+  sessions, audit, and client-grade sharing under MNSTRY runtime authority.
+
+## Output Shape
+
+Produce claim-first outputs:
+
+- Claim: the readiness statement being made.
+- Evidence: file paths, schema names, commands run, and observed behavior.
+- Authority: source, generated evidence, proposed claim, or runtime-owned.
+- Status: ready, warning, blocked, or proposed.
+- Fix path: the smallest next reviewable change.
+
+Do not introduce independent tenant semantics, new visibility terms, hidden
+provider boundaries, or runtime mutation claims. If a check cannot run, report
+the exact command, stderr, and blocker.
+
+## Safety And Hygiene
+
+- Keep package-facing output generic and placeholder-only.
+- Do not include person-specific, tenant-private, project-private, transcript,
+  support-bundle, local absolute path, agent-local state, key, token, or
+  credential material.
+- Prefer static inspection and existing defensive tests for security-sensitive
+  review work.
+- Frame checks as verifying that a control refuses, blocks, or fails closed.

package/src/analysis/adapter.mjs

@@ -0,0 +1,20 @@
+import fs from 'node:fs'
+
+export function analysisAdapterDryRun(manifestPath = null) {
+  const manifest = manifestPath && fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : {}
+  if (manifest.enabled === true) throw new Error('model-assisted analysis execution is disabled in this release')
+  if (manifest.endpoint || manifest.token || manifest.apiBase || manifest.proxyUrl) throw new Error('model-assisted analysis manifest must not declare network/provider egress')
+  return {
+    schema: 'mnstry.atelier-analysis-adapter-dry-run@v1',
+    provider: 'analysis',
+    enabled: false,
+    canonicalMutation: false,
+    output: 'atelier-claim@v1 proposed claims only',
+  }
+}
+
+export function runAnalysisAdapterCommand(argv = process.argv.slice(2)) {
+  const manifestArg = argv.find((arg) => arg.startsWith('--manifest='))
+  const report = analysisAdapterDryRun(manifestArg ? manifestArg.slice('--manifest='.length) : null)
+  console.log(JSON.stringify(report, null, 2))
+}

package/src/analysis/analysis-claim-contract.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(__dirname, '../..')
+
+export const manifestSchema = 'analysis-adapter-manifest@v1'
+export const claimSchema = 'atelier-claim@v1'
+export const provider = 'analysis'
+export const harnessPolicy = 'claim-only-local-disabled'
+export const localAnalysisRoot = '.mnstry/atelier/analysis'
+export const fixtureRoot = path.join(packageRoot, 'fixtures/analysis')
+
+export const defaultAnalysisClaimContract = {
+  schema: 'mnstry.atelier-analysis-claim-contract@v1',
+  provider,
+  claimSchema,
+  harnessPolicy,
+  authority: {
+    claimOnly: true,
+    frontMatterMutation: false,
+    graphRelationMutation: false,
+    publicExportFeed: false,
+    mcpFeed: false,
+    runtimeImport: false,
+    directCanonicalWrite: false,
+  },
+}
+
+const authorityPolicyKeys = new Set([
+  'claimOnly',
+  'frontMatterMutation',
+  'graphRelationMutation',
+  'publicExportFeed',
+  'mcpFeed',
+  'runtimeImport',
+  'directCanonicalWrite',
+])
+
+const forbiddenAuthorityKeys = new Map([
+  ['frontMatterMutation', 'front matter mutation'],
+  ['frontmatterMutation', 'front matter mutation'],
+  ['frontmatter', 'canonical front matter'],
+  ['frontMatter', 'canonical front matter'],
+  ['graphRelationMutation', 'graph relation mutation'],
+  ['graphRelations', 'graph relations'],
+  ['relations', 'graph relations'],
+  ['edges', 'graph relation mutation'],
+  ['publicExportFeed', 'public export feed'],
+  ['publicExport', 'public exports'],
+  ['publicExports', 'public exports'],
+  ['mcpFeed', 'MCP feed'],
+  ['runtimeImport', 'runtime import'],
+  ['runtimeApply', 'runtime import'],
+  ['directCanonicalWrite', 'direct canonical write'],
+  ['canonicalWrite', 'direct canonical write'],
+])
+
+const hiddenProviderKeys = new Map([
+  ['modelProvider', 'hidden model provider'],
+  ['apiKey', 'hidden model provider credential'],
+  ['apiToken', 'hidden model provider credential'],
+  ['secret', 'hidden model provider credential'],
+])
+
+const executionKeys = new Map([
+  ['execute', 'model-assisted analysis execution'],
+  ['executeCommand', 'model-assisted analysis execution command'],
+  ['runCommand', 'model-assisted analysis execution command'],
+  ['shellCommand', 'model-assisted analysis execution command'],
+  ['installCommand', 'model-assisted analysis install command'],
+  ['network', 'network access'],
+])
+
+const manifestRootKeys = new Set(['schema', 'provider', 'enabled', 'outputRoot', 'claimContract', 'harness', 'canonicalMutation', 'authority'])
+const manifestHarnessKeys = new Set(['policy', 'hiddenModelProvider', 'network', 'analysisExecution'])
+const manifestAuthorityKeys = new Set([...authorityPolicyKeys])
+const claimKeys = new Set(['schema', 'claimId', 'subject', 'predicate', 'object', 'provider', 'status', 'promoted', 'confidence', 'evidence', 'createdAt', 'notes'])
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function joinPath(base, key) {
+  return base ? `${base}.${key}` : String(key)
+}
+
+function valueAttemptsAuthority(value) {
+  return value === true || value === 'true' || value === 'enabled' || value === 'apply' || value === 'write'
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+export function collectContractAttempts(value, {
+  pathLabel = '',
+  attempts = [],
+  skipExecutionNetworkKey = false,
+} = {}) {
+  if (!value || typeof value !== 'object') return attempts
+  for (const [key, item] of Object.entries(value)) {
+    const current = joinPath(pathLabel, key)
+    if (forbiddenAuthorityKeys.has(key) && valueAttemptsAuthority(item)) {
+      attempts.push(`${current} attempts ${forbiddenAuthorityKeys.get(key)}`)
+    }
+    if (hiddenProviderKeys.has(key) && item != null && item !== false) {
+      attempts.push(`${current} attempts ${hiddenProviderKeys.get(key)}`)
+    }
+    if (executionKeys.has(key) && item != null && item !== false && !(skipExecutionNetworkKey && key === 'network')) {
+      if (key === 'network' && item === 'none') {
+        // Explicit no-network posture is allowed.
+      } else {
+        attempts.push(`${current} attempts ${executionKeys.get(key)}`)
+      }
+    }
+    if (item && typeof item === 'object') {
+      collectContractAttempts(item, {
+        pathLabel: current,
+        attempts,
+        skipExecutionNetworkKey,
+      })
+    }
+  }
+  return attempts
+}
+
+function validateLocalOutputRoot(outputRoot) {
+  const errors = []
+  if (typeof outputRoot !== 'string' || !outputRoot) {
+    errors.push('outputRoot is required')
+    return errors
+  }
+  if (path.isAbsolute(outputRoot)) errors.push('outputRoot must not be absolute')
+  const normalized = outputRoot.replaceAll('\\', '/')
+  if (normalized.split('/').includes('..')) errors.push('outputRoot must not escape via ..')
+  if (!(normalized === localAnalysisRoot || normalized.startsWith(`${localAnalysisRoot}/`))) {
+    errors.push(`outputRoot must live under ${localAnalysisRoot}`)
+  }
+  return errors
+}
+
+export function validateContractShape(contract = defaultAnalysisClaimContract) {
+  const errors = []
+  if (contract?.schema !== 'mnstry.atelier-analysis-claim-contract@v1') {
+    errors.push('contract schema must be mnstry.atelier-analysis-claim-contract@v1')
+  }
+  if (contract?.provider !== provider) errors.push('contract provider must be analysis')
+  if (contract?.claimSchema !== claimSchema) errors.push('contract claimSchema must be atelier-claim@v1')
+  if (contract?.harnessPolicy !== harnessPolicy) errors.push(`contract harnessPolicy must be ${harnessPolicy}`)
+  if (contract?.authority?.claimOnly !== true) errors.push('authority.claimOnly must be true')
+  for (const key of authorityPolicyKeys) {
+    if (key === 'claimOnly') continue
+    if (contract?.authority?.[key] !== false) errors.push(`authority.${key} must be false`)
+  }
+  errors.push(...collectContractAttempts(contract, { skipExecutionNetworkKey: true }))
+  return errors
+}
+
+export function validateManifest(manifest, { contract = defaultAnalysisClaimContract } = {}) {
+  const errors = validateContractShape(contract)
+  const warnings = []
+  const normalized = structuredClone(manifest || {})
+  if (!isPlainObject(normalized)) {
+    return { errors: ['manifest must be an object'], warnings, manifest: null }
+  }
+  for (const key of Object.keys(normalized)) {
+    if (!manifestRootKeys.has(key)) errors.push(`manifest has unknown property ${key}`)
+  }
+  if (normalized.schema !== manifestSchema) errors.push(`schema must be ${manifestSchema}`)
+  if (normalized.provider !== provider) errors.push('provider must be analysis')
+  if (normalized.enabled == null) {
+    normalized.enabled = false
+    warnings.push('enabled missing; defaulting to false')
+  }
+  if (normalized.enabled !== false) errors.push('enabled must be false until the operator explicitly installs an adapter')
+  errors.push(...validateLocalOutputRoot(normalized.outputRoot))
+  if (normalized.claimContract !== claimSchema) errors.push(`claimContract must be ${claimSchema}`)
+
+  const harness = normalized.harness || {}
+  if (!isPlainObject(harness)) errors.push('harness must be an object')
+  for (const key of Object.keys(harness)) {
+    if (!manifestHarnessKeys.has(key)) errors.push(`harness has unknown property ${key}`)
+  }
+  if (harness.policy !== harnessPolicy) errors.push(`harness.policy must be ${harnessPolicy}`)
+  if (harness.hiddenModelProvider !== false) errors.push('harness.hiddenModelProvider must be false')
+  if (harness.network !== 'none') errors.push('harness.network must be none')
+  if (harness.analysisExecution !== false) errors.push('harness.analysisExecution must be false')
+
+  if (normalized.canonicalMutation !== false) errors.push('canonicalMutation must be false')
+  const authority = normalized.authority || {}
+  if (!isPlainObject(authority)) errors.push('authority must be an object')
+  for (const key of Object.keys(authority)) {
+    if (!manifestAuthorityKeys.has(key)) errors.push(`authority has unknown property ${key}`)
+  }
+  if (authority.claimOnly !== true) errors.push('authority.claimOnly must be true')
+  for (const key of authorityPolicyKeys) {
+    if (key === 'claimOnly') continue
+    if (authority[key] !== false) errors.push(`authority.${key} must be false`)
+  }
+  errors.push(...collectContractAttempts(normalized, { skipExecutionNetworkKey: true }))
+  return { errors, warnings, manifest: normalized }
+}
+
+function normalizeOutputClaims(output) {
+  if (Array.isArray(output)) return output
+  if (isPlainObject(output) && Array.isArray(output.claims)) return output.claims
+  return null
+}
+
+export function validateAdapterOutput(output, { nodes = null, contract = defaultAnalysisClaimContract } = {}) {
+  const errors = validateContractShape(contract)
+  if (isPlainObject(output) && (Array.isArray(output.nodes) || Array.isArray(output.edges))) {
+    errors.push('model-assisted analysis output must be a single atelier-claim@v1 claim list, not native graph nodes/edges')
+    errors.push('native graph output attempts graph relation mutation')
+  }
+  const claims = normalizeOutputClaims(output)
+  if (!claims) {
+    errors.push('model-assisted analysis output must be a single atelier-claim@v1 claim list')
+    return { errors, claimCount: 0 }
+  }
+
+  for (const [index, claim] of claims.entries()) {
+    const label = `claims[${index}]`
+    if (!isPlainObject(claim)) {
+      errors.push(`${label} must be an object`)
+      continue
+    }
+    for (const key of Object.keys(claim)) {
+      if (!claimKeys.has(key)) errors.push(`${label} has unknown key ${key}`)
+    }
+    if (claim.schema !== claimSchema) errors.push(`${label}.schema must be ${claimSchema}`)
+    if (claim.provider !== provider) errors.push(`${label}.provider must be analysis`)
+    if (typeof claim.claimId !== 'string' || !claim.claimId.startsWith('claim:analysis:')) {
+      errors.push(`${label}.claimId must start with claim:analysis:`)
+    }
+    for (const key of ['subject', 'predicate', 'object']) {
+      if (typeof claim[key] !== 'string' || !claim[key]) errors.push(`${label}.${key} is required`)
+    }
+    if (claim.status !== 'proposed') errors.push(`${label}.status must be proposed`)
+    if (claim.promoted !== false) errors.push(`${label}.promoted must remain false`)
+    if (typeof claim.confidence !== 'number' || claim.confidence < 0 || claim.confidence > 1) {
+      errors.push(`${label}.confidence must be a number between 0 and 1`)
+    }
+    if (!Array.isArray(claim.evidence) || claim.evidence.length === 0) {
+      errors.push(`${label}.evidence must include at least one source reference`)
+    }
+    if (nodes && !nodes.some((node) => node?.id === claim.subject)) {
+      errors.push(`${label}.subject does not match a known graph node`)
+    }
+    errors.push(...collectContractAttempts(claim).map((attempt) => `${label}.${attempt}`))
+  }
+
+  return { errors, claimCount: claims.length }
+}
+
+function isJsonFile(file) {
+  return file.endsWith('.json')
+}
+
+export function checkFixtureSet({ root = fixtureRoot, nodes = null } = {}) {
+  const errors = []
+  let fixtureCount = 0
+  let invalidFixtureCount = 0
+  const validDir = path.join(root, 'valid')
+  const invalidDir = path.join(root, 'invalid')
+
+  if (fs.existsSync(validDir)) {
+    for (const name of fs.readdirSync(validDir).filter(isJsonFile).sort()) {
+      fixtureCount += 1
+      const result = validateAdapterOutput(readJson(path.join(validDir, name)), { nodes })
+      errors.push(...result.errors.map((error) => `${name}: ${error}`))
+    }
+  }
+  if (fs.existsSync(invalidDir)) {
+    for (const name of fs.readdirSync(invalidDir).filter(isJsonFile).sort()) {
+      invalidFixtureCount += 1
+      const result = validateAdapterOutput(readJson(path.join(invalidDir, name)), { nodes })
+      if (result.errors.length === 0) errors.push(`${name}: invalid fixture unexpectedly passed`)
+    }
+  }
+  return { errors, fixtureCount, invalidFixtureCount }
+}
+
+export function runAnalysisClaimContractCheck({
+  manifestPath = null,
+  fixtures = fixtureRoot,
+  contract = defaultAnalysisClaimContract,
+} = {}) {
+  const report = {
+    status: 'disabled',
+    enabled: false,
+    analysisExecuted: false,
+    networkCalls: false,
+    canonicalMutation: false,
+    errors: [],
+    warnings: [],
+  }
+
+  report.errors.push(...validateContractShape(contract))
+  if (manifestPath && fs.existsSync(manifestPath)) {
+    const manifestResult = validateManifest(readJson(manifestPath), { contract })
+    report.errors.push(...manifestResult.errors)
+    report.warnings.push(...manifestResult.warnings)
+    report.enabled = manifestResult.manifest?.enabled === true
+  } else if (manifestPath) {
+    report.warnings.push('manifest missing; model-assisted analysis remains disabled')
+  }
+  const fixtureResult = checkFixtureSet({ root: fixtures })
+  report.errors.push(...fixtureResult.errors)
+  report.fixtureCount = fixtureResult.fixtureCount
+  report.invalidFixtureCount = fixtureResult.invalidFixtureCount
+  report.status = report.errors.length ? 'failed' : 'disabled'
+  return report
+}
+
+function formatReport(report) {
+  return JSON.stringify(report, null, 2)
+}
+
+function main() {
+  const manifestArg = process.argv.find((arg) => arg.startsWith('--manifest='))
+  const manifestPath = manifestArg ? manifestArg.slice('--manifest='.length) : null
+  const report = runAnalysisClaimContractCheck({ manifestPath })
+  console.log(formatReport(report))
+  if (report.errors.length) process.exitCode = 1
+}
+
+const currentFile = fileURLToPath(import.meta.url)
+if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) {
+  main()
+}