@aiwg/cli 2026.9.3 → 2026.9.5

package/dist/src/writing/writing-receipt.js

@@ -0,0 +1,266 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { redactStructured } from '../governance/redaction.js';
+import { resolveProjectAiwgDirForWrite } from '../config/project-artifacts.js';
+const sha = z.string().regex(/^[a-f0-9]{64}$/);
+const id = z.string().min(1).max(120).regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/);
+const stableId = z.string().min(1).max(120).regex(/^[a-z0-9][a-z0-9.-]*$/).refine(value => !value.includes('..'));
+const isoDate = z.string().datetime();
+const hash = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => [key, canonicalize(child)]));
+    }
+    return value;
+}
+function receiptDigest(receipt) {
+    return hash(JSON.stringify(canonicalize(receipt)));
+}
+function rejectSensitiveReceipt(value) {
+    const redacted = redactStructured(value);
+    if (redacted.sensitivity !== 'none')
+        throw new Error('Writing receipt contains a known secret or credential field');
+}
+const budgetSchema = z.object({
+    limit: z.number().int().nonnegative(),
+    used: z.number().int().nonnegative(),
+    unit: z.enum(['tokens', 'utf8-bytes', 'characters']),
+    measurement: z.enum(['exact', 'upper-bound', 'estimated']),
+    tokenizerId: z.string().min(1).max(120),
+    tokenizerVersion: z.string().min(1).max(120),
+}).strict().refine(value => value.used <= value.limit, 'Budget use cannot exceed limit');
+const operationConfigSchema = z.object({
+    action: z.enum(['plan', 'proofread', 'draft', 'edit', 'continue']),
+    correctionIds: z.array(id).default([]),
+    channel: z.enum(['article', 'social', 'email', 'engineering', 'conversation']).optional(),
+    configSha256: sha.optional(),
+}).strict();
+const receiptInputBaseSchema = z.object({
+    schemaVersion: z.literal('aiwg.writing-receipt.v1').default('aiwg.writing-receipt.v1'),
+    id: stableId.optional(),
+    createdAt: isoDate.default(() => new Date().toISOString()),
+    operation: z.enum(['draft-from-notes', 'edit-existing', 'proofread-only', 'continue-author-text']),
+    profile: z.object({
+        id: stableId,
+        version: z.string().regex(/^\d+\.\d+\.\d+$/),
+        revision: z.number().int().positive(),
+        cacheEpoch: z.number().int().nonnegative(),
+        compiledModeSha256: sha.optional(),
+        fallback: z.boolean(),
+    }).strict(),
+    examples: z.object({
+        receiptSha256: sha.optional(),
+        cacheKey: sha.optional(),
+        selections: z.array(z.object({ sampleId: id, sha256: sha }).strict()).default([]),
+        budget: budgetSchema.optional(),
+        fallback: z.boolean().default(false),
+    }).strict().optional(),
+    modes: z.array(z.object({
+        id: stableId,
+        version: z.string().min(1).max(120),
+        profileSha256: sha.optional(),
+    }).strict()).default([]),
+    state: z.object({
+        selected: z.array(stableId).default([]),
+        delivered: z.array(stableId).default([]),
+        applied: z.array(stableId).default([]),
+        validated: z.array(stableId).default([]),
+        deliveredTo: z.enum(['local-transform-callback', 'none']),
+        fallback: z.enum(['none', 'unaltered']),
+    }).strict().optional(),
+    modelPrompt: z.object({
+        execution: z.enum(['none', 'local-callback', 'hosted']).default('none'),
+        provider: z.string().min(1).max(120).optional(),
+        model: z.string().min(1).max(120).optional(),
+        promptSha256: sha,
+        templateSha256: sha.optional(),
+        decoding: z.object({
+            temperature: z.number().finite().min(0).max(2).optional(),
+            topP: z.number().finite().min(0).max(1).optional(),
+            maxOutputTokens: z.number().int().positive().optional(),
+            seed: z.number().int().optional(),
+            stopSha256: sha.optional(),
+        }).strict().optional(),
+        promptConfigSha256: sha.optional(),
+        hostedVersion: z.object({
+            attested: z.literal(false),
+            reason: z.literal('Hosted provider prompt/version cannot be attested from this local receipt.'),
+        }).strict().optional(),
+    }).strict(),
+    inputs: z.array(z.object({
+        id,
+        role: z.enum(['source', 'author-notes', 'existing-draft', 'brief', 'configuration']),
+        sha256: sha,
+    }).strict()).min(1),
+    operationConfig: operationConfigSchema.optional(),
+    output: z.object({
+        sha256: sha,
+        path: z.string().min(1).max(2000).optional(),
+    }).strict().optional(),
+    budget: budgetSchema,
+    fallback: z.object({
+        applied: z.boolean(),
+        reason: z.string().min(1).max(400).optional(),
+    }).strict(),
+    validators: z.array(z.object({
+        id,
+        version: z.string().min(1).max(120),
+        sha256: sha.optional(),
+        outcome: z.enum(['pass', 'fail', 'uncertain', 'not-run']),
+    }).strict()).default([]),
+    evaluation: z.array(z.object({
+        id,
+        method: z.string().min(1).max(120),
+        sha256: sha,
+        outcome: z.enum(['pass', 'fail', 'uncertain', 'not-established']),
+    }).strict()).default([]),
+    authorAcceptance: z.object({
+        status: z.enum(['accepted', 'pending', 'rejected', 'not-required']),
+        acceptedAt: isoDate.optional(),
+        acceptedBy: z.string().min(1).max(120).optional(),
+    }).strict(),
+}).strict();
+const enforceReceiptRules = (value, ctx) => {
+    if (new Set(value.inputs.map(input => input.id)).size !== value.inputs.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Input IDs must be unique' });
+    }
+    if (value.fallback.applied && !value.fallback.reason) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Fallback receipts require a reason' });
+    }
+    if (!value.fallback.applied && value.fallback.reason) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Fallback reason is only valid when fallback is applied' });
+    }
+    if (value.authorAcceptance.status === 'accepted' && (!value.authorAcceptance.acceptedAt || !value.authorAcceptance.acceptedBy)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Accepted receipts require acceptedAt and acceptedBy' });
+    }
+    if (value.authorAcceptance.status !== 'accepted' && (value.authorAcceptance.acceptedAt || value.authorAcceptance.acceptedBy)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Acceptance identity is only valid for accepted receipts' });
+    }
+    if (new Set(value.modes.map(mode => mode.id)).size !== value.modes.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Mode IDs must be unique' });
+    }
+    if (value.state) {
+        const knownModes = new Set(value.modes.map(mode => mode.id));
+        const stateGroups = [value.state.selected, value.state.delivered, value.state.applied, value.state.validated];
+        if (stateGroups.some(group => new Set(group).size !== group.length)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Mode state IDs must be unique within each state set' });
+        }
+        if (stateGroups.some(group => group.some(modeId => !knownModes.has(modeId)))) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Mode state can reference only declared mode IDs' });
+        }
+        if (value.state.applied.some(modeId => !value.state.delivered.includes(modeId))) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Applied modes must be a subset of delivered modes' });
+        }
+        if (value.state.validated.some(modeId => !value.state.applied.includes(modeId))) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Validated modes must be a subset of applied modes' });
+        }
+        if (value.state.deliveredTo === 'none' && value.state.delivered.length > 0) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'No delivery target means no delivered modes' });
+        }
+        if (value.fallback.applied !== (value.state.fallback !== 'none')) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Mode state fallback must agree with receipt fallback' });
+        }
+    }
+    if (value.modelPrompt.execution !== 'hosted' && value.modelPrompt.hostedVersion) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Hosted uncertainty is only valid for hosted execution receipts' });
+    }
+    if ((value.fallback.applied || value.state?.fallback !== 'none') && value.state && (value.state.applied.length > 0 || value.state.validated.length > 0)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Fallback receipts cannot report applied or validated modes' });
+    }
+};
+const receiptInputSchema = receiptInputBaseSchema.superRefine(enforceReceiptRules);
+export const writingReceiptSchema = receiptInputBaseSchema.extend({ id: stableId, operationConfig: operationConfigSchema, receiptSha256: sha }).strict().superRefine(enforceReceiptRules);
+export function createWritingReceipt(input) {
+    const parsed = receiptInputSchema.parse(input);
+    const defaultAction = {
+        'draft-from-notes': 'draft',
+        'edit-existing': 'edit',
+        'proofread-only': 'proofread',
+        'continue-author-text': 'continue',
+    }[parsed.operation];
+    const body = {
+        ...parsed,
+        id: parsed.id ?? `wr-${hash(JSON.stringify(canonicalize({ ...parsed, createdAt: undefined }))).slice(0, 24)}`,
+        operationConfig: parsed.operationConfig ?? { action: defaultAction, correctionIds: [] },
+        modelPrompt: parsed.modelPrompt.execution === 'hosted' && !parsed.modelPrompt.hostedVersion
+            ? { ...parsed.modelPrompt, hostedVersion: { attested: false, reason: 'Hosted provider prompt/version cannot be attested from this local receipt.' } }
+            : parsed.modelPrompt,
+    };
+    rejectSensitiveReceipt(body);
+    const receiptSha256 = receiptDigest(body);
+    return writingReceiptSchema.parse({ ...body, receiptSha256 });
+}
+export function validateWritingReceipt(value) {
+    const parsed = writingReceiptSchema.parse(value);
+    const { receiptSha256, ...body } = parsed;
+    if (receiptDigest(body) !== receiptSha256)
+        throw new Error('Writing receipt integrity mismatch');
+    rejectSensitiveReceipt(parsed);
+    return parsed;
+}
+export function writingReceiptPath(cwd, receiptId) {
+    if (!/^[a-z0-9][a-z0-9.-]*$/.test(receiptId))
+        throw new Error('Invalid writing receipt ID');
+    return join(resolveProjectAiwgDirForWrite(cwd), 'writing', 'receipts', `${receiptId}.json`);
+}
+export async function writeWritingReceipt(cwd, receiptInput) {
+    const receipt = validateWritingReceipt(receiptInput);
+    const destination = writingReceiptPath(cwd, receipt.id);
+    await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+    const payload = JSON.stringify(receipt, null, 2) + '\n';
+    const existing = await readFile(destination, 'utf8').catch(error => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (existing !== null) {
+        if (existing === payload)
+            return { path: destination, sha256: hash(payload) };
+        throw new Error('Writing receipt already exists with different content');
+    }
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    const lock = `${destination}.lock`;
+    let locked = false;
+    try {
+        await mkdir(lock, { mode: 0o700 });
+        locked = true;
+        await writeFile(temporary, payload, { mode: 0o600, flag: 'wx' });
+        const raced = await readFile(destination, 'utf8').catch(error => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (raced !== null) {
+            if (raced === payload)
+                return { path: destination, sha256: hash(payload) };
+            throw new Error('Writing receipt already exists with different content');
+        }
+        await rename(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true });
+        if (locked)
+            await rm(lock, { recursive: true, force: true });
+    }
+    return { path: destination, sha256: hash(payload) };
+}
+export async function readWritingReceipt(cwd, receiptId) {
+    const path = writingReceiptPath(cwd, receiptId);
+    const payload = await readFile(path, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        throw new Error('Writing receipt is corrupt or not JSON');
+    }
+    return { receipt: validateWritingReceipt(parsed), path, sha256: hash(payload) };
+}
+//# sourceMappingURL=writing-receipt.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.9.3",
+  "version": "2026.9.5",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",

package/schemas/dataset/fortemi-live-qualification-receipt.v2.schema.json

@@ -0,0 +1,196 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aiwg.io/schemas/dataset/fortemi-live-qualification-receipt.v2.schema.json",
+  "title": "AIWG Fortemi Dataset Live Qualification Receipt v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contract",
+    "outcome",
+    "diagnostic",
+    "receiptDigest",
+    "bindings",
+    "observed",
+    "namespace",
+    "operations",
+    "mutation",
+    "resources",
+    "startedAt",
+    "endedAt"
+  ],
+  "properties": {
+    "contract": {
+      "const": "aiwg.fortemi-dataset-live-qualification/v2"
+    },
+    "outcome": {
+      "enum": [
+        "pending",
+        "supported"
+      ]
+    },
+    "diagnostic": {
+      "enum": [
+        "CONFORMANCE_FORTEMI_DATASET_CONTRACT_UNAVAILABLE",
+        "CONFORMANCE_FORTEMI_DATASET_PREFLIGHT_SUPPORTED"
+      ]
+    },
+    "receiptDigest": {
+      "$ref": "#/$defs/digest"
+    },
+    "bindings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "aiwgCommit",
+        "endpointFingerprint",
+        "toolSchemaDigest"
+      ],
+      "properties": {
+        "aiwgCommit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$"
+        },
+        "endpointFingerprint": {
+          "$ref": "#/$defs/digest"
+        },
+        "toolSchemaDigest": {
+          "$ref": "#/$defs/digest"
+        }
+      }
+    },
+    "observed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "serverName",
+        "serverVersion"
+      ],
+      "properties": {
+        "serverName": {
+          "$ref": "#/$defs/safe"
+        },
+        "serverVersion": {
+          "$ref": "#/$defs/safe"
+        }
+      }
+    },
+    "namespace": {
+      "type": "string",
+      "pattern": "^aiwg-dataset-qualification-[0-9a-f-]{36}$"
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "tool",
+          "compatible",
+          "code"
+        ],
+        "properties": {
+          "tool": {
+            "const": "manage_dataset_execution"
+          },
+          "compatible": {
+            "type": "boolean"
+          },
+          "code": {
+            "enum": [
+              "FORTEMI_DATASET_TOOL_SCHEMA_COMPATIBLE",
+              "FORTEMI_DATASET_TOOL_SCHEMA_DRIFT",
+              "FORTEMI_DATASET_TOOL_MISSING"
+            ]
+          }
+        }
+      }
+    },
+    "mutation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "authorized",
+        "attempted"
+      ],
+      "properties": {
+        "authorized": {
+          "const": false
+        },
+        "attempted": {
+          "const": false
+        }
+      }
+    },
+    "resources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "maxDurationMs",
+        "durationMs",
+        "maxToolCount",
+        "observedToolCount",
+        "maxSchemaBytes",
+        "observedSchemaBytes",
+        "networkAttempts",
+        "toolCalls"
+      ],
+      "properties": {
+        "maxDurationMs": {
+          "type": "integer",
+          "minimum": 250,
+          "maximum": 30000
+        },
+        "durationMs": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxToolCount": {
+          "const": 256
+        },
+        "observedToolCount": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 256
+        },
+        "maxSchemaBytes": {
+          "const": 1048576
+        },
+        "observedSchemaBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1048576
+        },
+        "networkAttempts": {
+          "const": 1
+        },
+        "toolCalls": {
+          "const": 0
+        }
+      }
+    },
+    "startedAt": {
+      "$ref": "#/$defs/time"
+    },
+    "endedAt": {
+      "$ref": "#/$defs/time"
+    }
+  },
+  "$defs": {
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "safe": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9._:/-]+$"
+    },
+    "time": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "Z$"
+    }
+  }
+}

package/schemas/dataset/fortemi-run-receipt/validation-1.0.1/authority.json

@@ -0,0 +1,12 @@
+{
+  "producer": "Fortemi/fortemi",
+  "producerIssue": 1131,
+  "consumerIssue": 2242,
+  "validationRevision": "1.0.1",
+  "wireSchemaVersion": "1.0.0",
+  "schemaSha256": "ef99ec0fb7cde6b59746c61ed80a308a25fe1a54fb3052f0f4af97798ee0af5c",
+  "source": "contracts/dataset-execution/validation/1.0.1/run-receipt.schema.json",
+  "producerCommit": "5ba6c39a7021ae30f28f4085813e8b2b88e27fd8",
+  "qualification": "bounded local PostgreSQL live run passed; final delivery pins pending",
+  "requestBindingRevision": "1.0.1"
+}