@rig-c/create 0.0.0-stage → 1.0.1

package/src/invariants.ts

@@ -0,0 +1,132 @@
+/** Pure, conservative translation of current interview records; no producer or file reads. */
+import { createHash } from 'node:crypto';
+import type { RigInvariants } from '@rig-c/core/rig';
+import type { Json, JsonObject } from './templates.ts';
+
+export const INVARIANTS_SPEC = 'rig-create/invariants@1';
+export interface InvariantFrom { question: string; verbatim_sha256: string | null; }
+export interface InvariantEntry {
+  invariant: RigInvariants;
+  from: InvariantFrom & { verbatim_sha256: string };
+  source_path: string;
+  value_path: string;
+}
+export interface InvariantGap {
+  gap: 'sentence_semantics' | 'vocabulary' | 'pending_answer' | 'pending_delegation' | 'pending_other' | 'inherited_answer' | 'not_applicable' | 'malformed_answer';
+  from: InvariantFrom;
+  source_path: string;
+  value_path: string;
+  sentence: string | null;
+  value: Json;
+}
+export interface InvariantsDocument {
+  spec: typeof INVARIANTS_SPEC;
+  /** Exact current records, including choice text, delegation reasons and additions; never history. */
+  sources: { question: string; path: string; record: Json }[];
+  entries: InvariantEntry[];
+  gaps: InvariantGap[];
+}
+const object = (v: Json | undefined): v is JsonObject => v !== null && typeof v === 'object' && !Array.isArray(v);
+const list = (v: Json | undefined): Json[] => Array.isArray(v) ? v : [];
+const text = (v: Json | undefined): v is string => typeof v === 'string' && v.trim().length > 0;
+const strings = (v: Json | undefined): v is string[] => Array.isArray(v) && v.length > 0 && v.every(text);
+const keys = (v: JsonObject, allowed: string[]): boolean => Object.keys(v).every(k => allowed.includes(k));
+const rows = (v: Json, predicate: (r: JsonObject) => boolean): boolean => Array.isArray(v) && v.length > 0 && v.every(r => object(r) && predicate(r));
+const unique = (values: Json[]): boolean => new Set(values).size === values.length;
+
+/** Only identically spelled, explicit structural readings qualify. No inference from part counts or prose. */
+function structural(key: string, value: Json): RigInvariants | null {
+  let valid = false;
+  switch (key) {
+    case 'meshSlots': case 'meshTriangles': valid = typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; break;
+    case 'axisBone': case 'massBone': valid = text(value); break;
+    case 'axes': valid = rows(value, r => keys(r, ['name', 'through', 'bones', 'tolerance']) && text(r.name)
+      && strings(r.through) && r.through.length === 2 && unique(r.through) && strings(r.bones) && unique(r.bones)
+      && typeof r.tolerance === 'number' && Number.isFinite(r.tolerance) && r.tolerance > 0 && r.tolerance < 90)
+      && unique((value as JsonObject[]).map(r => r.name as Json)); break;
+    case 'detached': valid = rows(value, r => keys(r, ['bone', 'notUnder', 'why']) && text(r.bone) && text(r.notUnder) && (r.why === undefined || text(r.why))); break;
+    case 'deformMayFold': valid = rows(value, r => keys(r, ['slot', 'why']) && text(r.slot) && text(r.why))
+      && unique((value as JsonObject[]).map(r => r.slot as Json)); break;
+    case 'consumerDrivenMix': valid = rows(value, r => keys(r, ['constraint', 'type', 'why']) && text(r.constraint) && (r.type === 'ik' || r.type === 'transform') && text(r.why))
+      && unique((value as JsonObject[]).map(r => `${String(r.type)}:${String(r.constraint)}`)); break;
+    case 'idleDrivesMeshes': valid = object(value) && keys(value, ['why']) && text(value.why); break;
+  }
+  // Core resolves names and enforces the rig. Shape acceptance here is not a passed core check.
+  return valid ? { [key]: structuredClone(value) } as RigInvariants : null;
+}
+
+export function translateInvariants(project: JsonObject): InvariantsDocument {
+  const result: InvariantsDocument = { spec: INVARIANTS_SPEC, sources: [], entries: [], gaps: [] };
+  const visit = (question: string, path: string, raw: Json, addition = false): void => {
+    result.sources.push({ question, path, record: structuredClone(raw) });
+    const answer = object(raw) ? raw : {};
+    const sentence = typeof answer.verbatim === 'string' ? answer.verbatim : null;
+    const from: InvariantFrom = { question, verbatim_sha256: sentence === null ? null : createHash('sha256').update(sentence, 'utf8').digest('hex') };
+    const gap = (kind: InvariantGap['gap'], value_path: string, value: Json): void => {
+      result.gaps.push({ gap: kind, from: { ...from }, source_path: path, value_path, sentence, value: structuredClone(value) });
+    };
+    const leaves = (value: Json, at: string): void => {
+      if (Array.isArray(value) && value.length) value.forEach((v, i) => leaves(v, `${at}[${i}]`));
+      else if (object(value) && Object.keys(value).length) for (const [k, v] of Object.entries(value)) leaves(v, `${at}[${JSON.stringify(k)}]`);
+      else gap('vocabulary', at, value);
+    };
+    const reading = (value: Json, at: string): void => {
+      if (object(value)) {
+        if (!Object.keys(value).length) leaves(value, at);
+        for (const [k, v] of Object.entries(value)) {
+          const valuePath = `${at}[${JSON.stringify(k)}]`;
+          const invariant = sentence === null ? null : structural(k, v);
+          if (invariant !== null) result.entries.push({ invariant, from: { question, verbatim_sha256: from.verbatim_sha256 as string }, source_path: path, value_path: valuePath });
+          else leaves(v, valuePath);
+        }
+      } else leaves(value, at);
+    };
+    if (!object(raw)) gap(raw === null ? 'pending_answer' : 'malformed_answer', path, raw);
+    else if (answer.basis === 'inherited') gap('inherited_answer', path, raw);
+    else if (answer.not_applicable === true) gap('not_applicable', path, raw);
+    else {
+      // Retain ALL words, including concepts absent from value. This is an explicit semantic gap,
+      // not an NLP claim that the interpreter understood each sentence or verified agreement.
+      if (sentence !== null) gap('sentence_semantics', `${path}.verbatim`, sentence);
+      else gap('malformed_answer', path, raw);
+      if (!addition && answer.delegated !== true && answer.delegated !== false) gap('malformed_answer', path, raw);
+      if (answer.value !== undefined && (answer.delegated === false || addition)) {
+        // An Other-pending answer has value:null, but other picks/fragments are still retained below.
+        reading(answer.value, `${path}.value`);
+      }
+      const decision = object(answer.agent_decision) ? answer.agent_decision : null;
+      const decided = decision !== null && decision.value !== undefined && text(decision.reasoning);
+      if (decided) reading(decision.value as Json, `${path}.agent_decision.value`);
+      const asks = list(answer.asks).filter(object);
+      const delegated = asks.filter(a => a.state === 'delegated');
+      if (answer.delegated === true && !decided) gap('pending_delegation', `${path}.agent_decision`, answer.agent_decision ?? null);
+      else if (decision !== null && !decided && delegated.length === 0) gap('pending_delegation', `${path}.agent_decision`, decision);
+      for (const ask of delegated) {
+        const landed = decided && (!object(answer.choice) || list(decision?.fragments).some(f => object(f) && f.ask === ask.id && f.fragment !== undefined));
+        if (!landed) gap('pending_delegation', `${path}.asks[${String(ask.id)}]`, ask);
+      }
+      for (const ask of asks.filter(a => a.state === 'other-pending')) gap('pending_other', `${path}.asks[${String(ask.id)}]`, ask);
+      // Completed Other fragments are already in value. Only read picks while a pending
+      // Other suppresses that aggregate; no option-file reads or reassembly.
+      if (object(answer.choice)) list(answer.choice.picks).forEach((pick, i) => {
+        if (!object(pick)) return;
+        if (pick.other_text !== undefined) gap('sentence_semantics', `${path}.choice.picks[${i}].other_text`, pick.other_text);
+        if (asks.some(a => a.state === 'other-pending') && pick.other_fragment !== undefined) reading(pick.other_fragment, `${path}.choice.picks[${i}].other_fragment`);
+      });
+      if (answer.delegated === false && answer.value === undefined) gap('malformed_answer', `${path}.value`, null);
+    }
+    list(answer.additions).forEach((addition, i) => visit(question, `${path}.additions[${i}]`, addition, true));
+  };
+  const interview = object(project.interview) ? project.interview : {};
+  const collect = (records: Json[], prefix: string, field: string): void => {
+    records.forEach((record, i) => {
+      if (!object(record)) { visit(`${prefix}[${i}]`, `${prefix}[${i}]`, record); return; }
+      const question = typeof record.id === 'string' ? record.id : `${prefix}[${i}]`;
+      visit(question, `${prefix}[${question}].${field}`, record[field] ?? null);
+    });
+  };
+  collect(list(interview.framing), 'interview.framing', 'answer');
+  collect(list(interview.waypoints), 'interview.waypoints', 'guide');
+  collect(list(object(interview.post) ? interview.post.items : undefined), 'interview.post.items', 'guide');
+  return result;
+}

package/src/job-acts.ts

@@ -0,0 +1,80 @@
+/** Writer routing for finalized acts. No event transport or automatic ingestion. */
+import type { ActV3 } from '@rig-c/review/job-host';
+import { asArray, isObject } from './check.ts';
+import { stageOfStep } from './stages.ts';
+import type { JsonObject } from './templates.ts';
+
+export interface PendingJobAct {
+  actId: string;
+  kind: ActV3['kind'];
+  subject: string;
+  at: string;
+  args: string[] | null;
+  command: string | null;
+  unavailable?: { code: 'JOB_ACTS_WRITER_UNAVAILABLE'; message: string };
+}
+
+function shellWord(value: string): string {
+  return /^[A-Za-z0-9_./:-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+export function pendingJobActs(project: JsonObject, acts: readonly ActV3[], root: string): PendingJobAct[] {
+  const ingested = new Set(asArray(project.review_acts).filter(isObject).map(row => JSON.stringify([row.jobId, row.actId])));
+  const signoffs = asArray(project.signoffs).filter(isObject);
+  const seen = new Set<string>();
+  return acts.flatMap(act => {
+    const key = JSON.stringify([act.jobId, act.actId]);
+    if (seen.has(key) || ingested.has(key) || signoffs.some(row => row.source === `review act ${act.jobId}/${act.actId}`)) return [];
+    seen.add(key);
+    let subject: string = act.kind;
+    let args: string[] | null = null;
+    switch (act.kind) {
+      case 'review-verdict': {
+        const selector = act.source.selector;
+        subject = act.value.stage;
+        if (selector && (selector.kind === 'rig' || selector.kind === 'post')
+          && act.value.stage === (selector.kind === 'rig' ? 'rig-review' : 'direction-review')) {
+          subject = `${selector.kind} v${selector.version} / ${act.value.stage}`;
+          args = ['review', String(selector.version), root];
+        }
+        break;
+      }
+      case 'parts-verdict': {
+        const selector = act.source.selector;
+        if (selector?.kind === 'draft') {
+          subject = `draft ${selector.id}`;
+          args = ['parts-review', root];
+        }
+        break;
+      }
+      case 'interview-picks':
+        subject = `question ${act.value.questionId}`;
+        args = ['interview-answer', act.value.questionId, root];
+        break;
+      case 'signoff':
+        subject = `stage ${act.value.stage}`;
+        args = ['signoff', act.value.stage, root];
+        break;
+      case 'checkpoint': {
+        const step = asArray(isObject(project.plan) ? project.plan.steps : undefined).filter(isObject).find(step => step.id === act.value.planStepId);
+        subject = `checkpoint ${act.value.planStepId}`;
+        if (step && (step.phase === 'rig' || step.phase === 'post')) {
+          const stage = stageOfStep(step.phase, String(step.id));
+          subject += ` / ${stage}`;
+          args = ['signoff', stage, root, '--checkpoint', act.value.planStepId];
+        }
+        break;
+      }
+    }
+    if (args) args.push('--from-review', act.actId);
+    return [{ actId: act.actId, kind: act.kind, subject, at: act.at, args,
+      command: args ? ['rig-create', ...args].map(shellWord).join(' ') : null,
+      ...(args ? {} : { unavailable: { code: 'JOB_ACTS_WRITER_UNAVAILABLE' as const,
+        message: `project.json: act ${act.actId} (${subject}) has no current writer target; restore its plan step or use a supported Review subject before ingestion` } }) }];
+  });
+}
+
+export function jobActsText(result: { acts: readonly PendingJobAct[] }): string {
+  if (!result.acts.length) return 'job: no finalized acts awaiting ingestion';
+  return result.acts.map(act => `${act.actId} ${act.kind} ${act.subject} at ${act.at}\n  ${act.command ?? `${act.unavailable!.code}: ${act.unavailable!.message}`}`).join('\n');
+}

package/src/job-advance.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobHash, jobPrivateRoot, readWriterBinding } from './job-outbox.ts';
+import { publicationSelector } from './job-publication.ts';
+import { acquireBoundJobWrite, prepareVersionIntent, publishCommittedVersion } from './job-writer.ts';
+import { refuse } from './refusal.ts';
+import { readVersions, type PostVersion, type RigVersion } from './review.ts';
+import type { JsonObject } from './templates.ts';
+
+export function isPublishAdvanceStage(stage: string): stage is 'rig-review' | 'direction-review' {
+  return stage === 'rig-review' || stage === 'direction-review';
+}
+
+export function acquireAdvanceJobWrite(dir: string, stage: string): () => void {
+  return isPublishAdvanceStage(stage) ? acquireBoundJobWrite(dir) : () => {};
+}
+
+function currentAdvanceVersion(project: JsonObject, stage: 'rig-review' | 'direction-review'): number {
+  const versions = readVersions(project);
+  if (stage === 'rig-review') {
+    const current = versions.rigs.filter(r => r.live).reduce<RigVersion | null>((a, r) => (a === null || r.n > a.n ? r : a), null);
+    if (current === null) {
+      refuse('JOB_PUBLICATION_INVALID', 'versions: rig-review requires a live rig version to publish; record rig-create rig-version <n> before advancing');
+    }
+    return current.n;
+  }
+  const current = versions.posts.filter(p => p.live).reduce<PostVersion | null>((a, p) => (a === null || p.n > a.n ? p : a), null);
+  if (current === null) {
+    refuse('JOB_PUBLICATION_INVALID', 'versions: direction-review requires a live post version to publish; record rig-create direction write <n> before advancing');
+  }
+  return current.n;
+}
+
+function defaultWriteRecord(temp: string, target: string, bytes: Buffer): void {
+  writeFileSync(temp, bytes, { flag: 'wx' });
+  renameSync(temp, target);
+}
+
+export function commitAdvance(
+  dir: string,
+  file: string,
+  project: JsonObject,
+  writeRecord: (temp: string, target: string, bytes: Buffer) => void = defaultWriteRecord,
+): void {
+  const stage = String(project.stage);
+  const serialized = `${JSON.stringify(project, null, 2)}\n`;
+  if (!isPublishAdvanceStage(stage) || !readWriterBinding(dir)) {
+    writeFileSync(file, serialized);
+    return;
+  }
+  const n = currentAdvanceVersion(project, stage);
+  publicationSelector(project, n);
+  const recordBytes = Buffer.from(serialized);
+  const publicationIntent = prepareVersionIntent(dir, recordBytes, n);
+  const temp = join(dir, `.project.json.advance-${process.pid}-${Date.now()}`);
+  try {
+    writeRecord(temp, file, recordBytes);
+  } finally {
+    rmSync(temp, { force: true });
+    if (publicationIntent && (!existsSync(file) || jobHash(readFileSync(file)) !== publicationIntent.recordHash)) {
+      rmSync(join(jobPrivateRoot(dir), 'outbox', `${publicationIntent.id}.json`), { force: true });
+    }
+  }
+  publishCommittedVersion(dir, n);
+}

package/src/job-close.ts

@@ -0,0 +1,226 @@
+import { readFileSync, realpathSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import {
+  startJobHost,
+  type JobHostAttachFailure,
+  type JobHostOptions,
+  type JobHostReuseBinding,
+  type JobOwnerHost,
+  type JobPublicationReader,
+} from '@rig-c/review/job-host';
+import {
+  acquireJobLock,
+  JOB_BINDING_FILE,
+  pendingPublications,
+  readWriterBinding,
+  type JobIdentity,
+  type WriterBinding,
+} from './job-outbox.ts';
+import { refuse } from './refusal.ts';
+
+function isAttachRefused(error: unknown): error is Extract<JobHostAttachFailure, { code: 'JOB_HOST_ATTACH_REFUSED' }> {
+  return typeof error === 'object' && error !== null
+    && (error as { code?: unknown }).code === 'JOB_HOST_ATTACH_REFUSED'
+    && typeof (error as { reason?: unknown }).reason === 'string'
+    && typeof (error as { phase?: unknown }).phase === 'string';
+}
+
+function isReuseMismatch(error: unknown): error is Extract<JobHostAttachFailure, { code: 'JOB_HOST_REUSE_MISMATCH' }> {
+  return typeof error === 'object' && error !== null
+    && (error as { code?: unknown }).code === 'JOB_HOST_REUSE_MISMATCH'
+    && typeof (error as { field?: unknown }).field === 'string'
+    && 'expected' in error && 'actual' in error;
+}
+
+function closeReuseBinding(identity: JobIdentity): JobHostReuseBinding {
+  return {
+    root: identity.root,
+    stateDir: identity.stateDir,
+    fingerprint: identity.fingerprint,
+    reviewer: { id: identity.reviewer.id, role: identity.reviewer.role },
+    readerId: identity.readerId,
+    bindingId: identity.bindingId,
+    partsEnumeratorId: identity.partsEnumeratorId,
+    partsEnumeratorVersion: identity.enumeratorVersion,
+    apiSchema: identity.apiSchema as JobHostReuseBinding['apiSchema'],
+    actSchema: identity.actSchema as JobHostReuseBinding['actSchema'],
+  };
+}
+
+export const failClosedCloseReadPublished: JobPublicationReader = async () => {
+  refuse('JOB_HOST_REUSE_MISMATCH', 'project.json: close attach must not invoke readPublished; reopen the live job at the current pin before publishing');
+};
+
+export function failClosedCloseEnumerate(): never {
+  refuse('JOB_HOST_REUSE_MISMATCH', 'project.json: close attach must not invoke partsEnumerator.enumerate; reopen the live job at the current pin before publishing');
+}
+
+export async function failClosedCloseInstallBinding(): Promise<never> {
+  refuse('JOB_HOST_REUSE_MISMATCH', 'project.json: close attach must not install a writer binding');
+}
+
+export function closeHostOptions(binding: WriterBinding): JobHostOptions {
+  const { identity } = binding;
+  return {
+    root: identity.root,
+    stateDir: identity.stateDir,
+    fingerprint: identity.fingerprint,
+    reviewer: { id: identity.reviewer.id, role: identity.reviewer.role },
+    readerId: identity.readerId,
+    readPublished: failClosedCloseReadPublished,
+    ...(identity.publicationMode ? { publicationMode: identity.publicationMode, readRecordPublished: () => refuse('JOB_HOST_REUSE_MISMATCH', 'project.json: close attach must not invoke the record reader; reopen the live job before publishing') } : {}),
+    partsEnumeratorId: identity.partsEnumeratorId,
+    partsEnumerator: {
+      version: identity.enumeratorVersion,
+      enumerate: failClosedCloseEnumerate,
+    },
+    bindingId: identity.bindingId,
+    installWriterBinding: failClosedCloseInstallBinding,
+    reuseOnly: {
+      expected: {
+        jobId: binding.jobId,
+        origin: binding.origin,
+        listenerIncarnation: binding.listenerIncarnation,
+        binding: closeReuseBinding(identity),
+      },
+    },
+  };
+}
+
+function assertStoredCloseBinding(root: string, binding: WriterBinding): void {
+  const identity = binding.identity as Partial<JobIdentity> | null | undefined;
+  if (
+    typeof identity !== 'object' || identity === null
+    || typeof identity.root !== 'string'
+    || typeof identity.stateDir !== 'string'
+    || typeof identity.fingerprint !== 'string'
+    || typeof identity.reviewer !== 'object' || identity.reviewer === null
+    || typeof identity.reviewer.id !== 'string'
+    || (identity.reviewer.role !== 'owner' && identity.reviewer.role !== 'delegate')
+    || typeof identity.readerId !== 'string'
+    || typeof identity.bindingId !== 'string'
+    || typeof identity.partsEnumeratorId !== 'string'
+    || typeof identity.apiSchema !== 'string'
+    || typeof identity.actSchema !== 'string'
+    || typeof identity.enumeratorVersion !== 'string'
+  ) {
+    refuse('JOB_BINDING_INVALID', 'project.json: malformed private live-job binding; reopen the job through rig-create job open');
+  }
+  if (identity.root !== root) {
+    refuse('JOB_HOST_REUSE_MISMATCH', `project.json: root expected=${JSON.stringify(identity.root)} found=${JSON.stringify(root)}; restore the bound host configuration, then run rig-create job close`);
+  }
+  let project: { review_job?: unknown };
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(root, 'project.json'), 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw Error();
+    project = parsed as { review_job?: unknown };
+  } catch {
+    refuse('PROJECT_JSON_INVALID', 'project.json: project record is not a JSON object');
+  }
+  if (project.review_job !== undefined) {
+    if (
+      typeof project.review_job !== 'object' || project.review_job === null || Array.isArray(project.review_job)
+      || typeof (project.review_job as { jobId?: unknown }).jobId !== 'string'
+      || typeof (project.review_job as { origin?: unknown }).origin !== 'string'
+    ) {
+      refuse('JOB_BINDING_INVALID', 'project.json: malformed review_job locator; reopen the job through rig-create job open');
+    }
+    const locator = project.review_job as { jobId: string; origin: string };
+    if (locator.jobId !== binding.jobId) {
+      refuse('JOB_HOST_REUSE_MISMATCH', `project.json: jobId expected=${JSON.stringify(locator.jobId)} found=${JSON.stringify(binding.jobId)}; restore the bound host configuration, then run rig-create job close`);
+    }
+    if (locator.origin !== binding.origin) {
+      refuse('JOB_HOST_REUSE_MISMATCH', `project.json: origin expected=${JSON.stringify(locator.origin)} found=${JSON.stringify(binding.origin)}; restore the bound host configuration, then run rig-create job close`);
+    }
+  }
+  if (!binding.listenerIncarnation) {
+    refuse('JOB_HOST_REUSE_MISMATCH', 'project.json: listenerIncarnation expected=a bound listener found=absent in the private binding; reopen the live job through rig-create job open, then run rig-create job close');
+  }
+}
+
+/**
+ * Close-only attachment boundary: uses the stored private binding's hook IDs and
+ * `enumeratorVersion` so a live host opened before a pin bump or reader ID bump can
+ * still be retired without weakening normal publication/reconcile/attach checks.
+ */
+export async function attachCreateJobForClose(
+  root: string,
+  binding: WriterBinding,
+  startHost: (options: JobHostOptions) => Promise<JobOwnerHost> = startJobHost,
+): Promise<JobOwnerHost> {
+  assertStoredCloseBinding(root, binding);
+  let host: JobOwnerHost;
+  try {
+    host = await startHost(closeHostOptions(binding));
+  } catch (error) {
+    if (isAttachRefused(error)) {
+      refuse('JOB_HOST_ATTACH_REFUSED', `project.json: live host attach refused (reason=${error.reason}, phase=${error.phase}); reopen or restore the bound live host before rig-create job close`);
+    }
+    if (isReuseMismatch(error)) {
+      refuse('JOB_HOST_REUSE_MISMATCH', `project.json: ${error.field} expected=${JSON.stringify(error.expected)} found=${JSON.stringify(error.actual)}; restore the bound host configuration, then run rig-create job close`);
+    }
+    if (error instanceof Error) {
+      const code = (error as Error & { code?: string }).code;
+      if (code === 'JOB_HOST_REUSE_MISMATCH') {
+        refuse('JOB_HOST_REUSE_MISMATCH', `project.json: ${error.message}; restore the bound host options before rig-create job close`);
+      }
+      if (code && ['JOB_REQUEST_INVALID', 'JOB_AUTHORITY_REFUSED', 'JOB_PARTS_ENUMERATOR_UNSUPPORTED', 'JOB_SOURCE_UNRETAINABLE'].includes(code)) {
+        refuse('JOB_BINDING_INVALID', `project.json: malformed private live-job binding (${code}); reopen the job through rig-create job open`);
+      }
+    }
+    throw error;
+  }
+  if (!host.reused || host.session.jobId !== binding.jobId || host.origin !== binding.origin) {
+    host.stop();
+    refuse('JOB_HOST_REUSE_MISMATCH', `project.json: host incarnation expected=${binding.jobId}@${binding.origin} found=${host.session.jobId}@${host.origin} reused=${host.reused}; restore the original live host before rig-create job close`);
+  }
+  return host;
+}
+
+export async function closeCreateJob(
+  root: string,
+  startHost: (options: JobHostOptions) => Promise<JobOwnerHost> = startJobHost,
+): Promise<void> {
+  root = realpathSync(root);
+  const release = acquireJobLock(root)!;
+  try {
+    if (pendingPublications(root).length) {
+      refuse('JOB_PUBLISH_PENDING', 'project.json: a committed publication remains pending; run rig-create job reconcile before closing');
+    }
+    const binding = readWriterBinding(root);
+    if (!binding) refuse('JOB_BINDING_INVALID', 'project.json: no writer-owned job binding; open the live job first');
+    const host = await attachCreateJobForClose(root, binding, startHost);
+    try {
+      try {
+        host.session.authorize('consumer', `Bearer ${binding.fetchCapability}`);
+      } catch {
+        refuse('JOB_BINDING_INVALID', 'project.json: writer binding fetchCapability is not authorized for the bound live job; restore the writer-owned binding before rig-create job close');
+      }
+      const response = await host.ports.handleJobApi(new Request(`${host.origin}/jobs/${binding.jobId}/api`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${host.session.hostCredentials().agent}`, 'content-type': 'application/json' },
+        body: JSON.stringify({
+          schema: binding.identity.apiSchema,
+          verb: 'close',
+          jobId: binding.jobId,
+          requestId: 'create-close',
+          idempotencyKey: 'create-close',
+          expectedGeneration: host.session.status().generation,
+          reason: 'producer-close',
+        }),
+      }));
+      const result = await response.json() as { ok: boolean };
+      if (!result.ok) refuse('JOB_BINDING_INVALID', 'project.json: review refused close; restore the bound live host and retry rig-create job close');
+      const current = readWriterBinding(root);
+      if (!current || !isDeepStrictEqual(current, binding)) {
+        refuse('JOB_BINDING_INVALID', 'project.json: private live-job binding changed during close; restore the writer-owned binding');
+      }
+      rmSync(join(root, JOB_BINDING_FILE));
+    } finally {
+      host.stop();
+    }
+  } finally {
+    release();
+  }
+}