From fad7b86588b1df98dd2611e1d5cd32a0eaca4ed3 Mon Sep 17 00:00:00 2001 From: humuhumu33 <68450279+humuhumu33@users.noreply.github.com> Date: Mon, 16 Nov 2026 13:06:09 +0000 Subject: [PATCH 1/2] Re-pin prism-code to 0.9.2: the shell carries its journey and browser files byte for byte Since 0.9.0 the checker, renderer and reader import stateful.mjs and render-stateful.mjs, and the archive reader imports uorc.mjs, so the copy list names them. complete.mjs and spec-schema.mjs, the draft form of prism/spec/1, are carried and not yet called. Co-Authored-By: Claude Fable 5.2 --- studio/shell/prism-code/src/archive.mjs | 149 ++++- studio/shell/prism-code/src/attestations.mjs | 23 +- studio/shell/prism-code/src/inspect.mjs | 4 +- studio/shell/prism-code/src/provenance.mjs | 14 +- studio/shell/prism-code/src/replay.mjs | 12 +- studio/shell/prism-code/src/uorc.mjs | 159 ++++++ studio/shell/prism-code/src/vendor/verify.mjs | 451 ++++++++++++++- studio/shell/prism-code/src/version.mjs | 6 +- studio/shell/prism/complete.mjs | 348 ++++++++++++ studio/shell/prism/render-stateful.mjs | 523 ++++++++++++++++++ studio/shell/prism/render.mjs | 69 ++- studio/shell/prism/session.mjs | 73 ++- studio/shell/prism/spec-file.mjs | 34 +- studio/shell/prism/spec-schema.mjs | 66 +++ studio/shell/prism/spec.mjs | 33 +- studio/shell/prism/stateful.mjs | 493 +++++++++++++++++ studio/tools/kernel.mjs | 2 +- studio/tools/prism_journey.mjs | 13 +- studio/tools/prism_template.mjs | 2 +- 19 files changed, 2400 insertions(+), 74 deletions(-) create mode 100644 studio/shell/prism-code/src/uorc.mjs create mode 100644 studio/shell/prism/complete.mjs create mode 100644 studio/shell/prism/render-stateful.mjs create mode 100644 studio/shell/prism/spec-schema.mjs create mode 100644 studio/shell/prism/stateful.mjs diff --git a/studio/shell/prism-code/src/archive.mjs b/studio/shell/prism-code/src/archive.mjs index 5ea5ff7f..3e930775 100644 --- a/studio/shell/prism-code/src/archive.mjs +++ b/studio/shell/prism-code/src/archive.mjs @@ -1,6 +1,9 @@ /** - * Reader for the Hologram v4 `.holo` application archive that PrismPM - * composes (`SPEC.md` §3, `crates/prismpm/src/holo/archive.rs`, encoded through + * Reader for the `.holo` application archive. PrismPM writes holo v5, a UORC + * archive of ordered objects named by κ (ADR-017, `src/uorc.mjs`); the + * Hologram physical-v4 archive below stays readable and is never written. + * + * Legacy v4 is the archive PrismPM composed before v5 (`SPEC.md` §3, `crates/prismpm/src/holo/archive.rs`, encoded through * `Foundation.Holo.V1.Wire`). * * Layout, little-endian: @@ -17,10 +20,16 @@ * blob. A content blob starts with its 71-byte `blake3:` label. */ import { DigestMismatchError, fail } from './errors.mjs'; -import { blake3Hex, kappa } from './blake3.mjs'; +import { blake3Hex, kappa as v4Label } from './blake3.mjs'; +import { isUorc, kappa, layout } from './uorc.mjs'; export const MAGIC = 'HOLO'; export const VERSION = 4; +/** Holo v5 (ADR-017): schema of the manifest object and the roles of the ordered objects. */ +export const MANIFEST_SCHEMA_V5 = 'prism/holo/5'; +export const PROVENANCE_SCHEMA_V5 = 'prismpm/model-provenance/2'; +export const ROLES_V5 = Object.freeze(['manifest', 'source-manifest', 'provenance', 'capabilities', 'guest', 'view', 'model']); +export const ROLE_ATTESTATIONS = 'attestations'; export const KIND = Object.freeze({ APP_MANIFEST: 15, METADATA: 8, EXTENSION: 14, CONTENT_BLOB: 16 }); export const LABEL_LENGTH = 71; export const FOOTER_LENGTH = 32; @@ -68,6 +77,7 @@ function isLabel(bytes) { */ export function parseArchive(source) { const bytes = asBytes(source); + if (isUorc(bytes)) return parseArchiveV5(bytes); if (bytes.length < HEADER_LENGTH + FOOTER_LENGTH) fail('archive.bounds', 'archive shorter than header and footer'); const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength); const magic = String.fromCharCode(bytes[0], bytes[1], bytes[2], bytes[3]); @@ -163,7 +173,7 @@ export function parseArchive(source) { if (!isLabel(labelBytes)) fail('archive.blob', `content blob ${blobs.length} has no blake3 label`); const label = decoder.decode(labelBytes); const content = b.subarray(LABEL_LENGTH); - const actual = kappa(content); + const actual = v4Label(content); if (actual !== label) labelMismatches.push({ section: section.index, label, actual }); blobs.push({ label, content, section: section.index }); break; @@ -202,6 +212,79 @@ export function parseArchive(source) { }; } +const hexOf = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join(''); + +/** + * Parse a holo v5. The result has the v4 reader's shape (sections, blobs, + * extensions, manifest labels, verification) so every consumer reads both: + * each object is a section whose `kind` is its role, the provenance object is + * the model extension and the attestation object the attestation extension. + */ +function parseArchiveV5(bytes) { + const { objects, sealed, seal, preimage } = layout(bytes); + if (objects.length !== ROLES_V5.length && objects.length !== ROLES_V5.length + 1) { + fail('archive.bounds', `a v5 application holo holds ${ROLES_V5.length} objects, or ${ROLES_V5.length + 1} when signed; this one holds ${objects.length}`); + } + const roles = [...ROLES_V5, ROLE_ATTESTATIONS]; + const sections = objects.map((object, index) => ({ index, kind: roles[index], offset: object.offset, length: object.length, body: object.bytes })); + const text = (slice, what) => { + try { + return decoder.decode(slice); + } catch { + if (!sealed) throw new DigestMismatchError(`integrity failure: the holo was altered: its seal does not match, and ${what} is not UTF-8`, { check: 'holo.integrity' }); + return fail('archive.manifest', `${what} is not UTF-8`); + } + }; + const manifestText = text(objects[0].bytes, 'the manifest'); + let holoManifest; + try { + holoManifest = JSON.parse(manifestText); + } catch (error) { + if (!sealed) throw new DigestMismatchError('integrity failure: the holo was altered: its seal does not match', { check: 'holo.integrity', cause: error }); + fail('archive.manifest', `the manifest is not JSON: ${error.message}`); + } + if (holoManifest?.schema !== MANIFEST_SCHEMA_V5) fail('archive.manifest', `the manifest schema is ${JSON.stringify(holoManifest?.schema)}, expected ${MANIFEST_SCHEMA_V5}`); + const layer = (kind) => (Array.isArray(holoManifest.layers) ? holoManifest.layers.find((l) => l.kind === kind) : undefined); + const labels = [holoManifest.requires, layer('wasm')?.kappa, layer('view')?.kappa]; + const blobs = [3, 4, 5, 6].map((index) => ({ label: kappa(objects[index].bytes), content: objects[index].bytes, section: index })); + const extensions = [ + { name: MODEL_EXTENSION, payload: objects[2].bytes, text: text(objects[2].bytes, 'the provenance object'), section: 2 }, + ]; + if (objects.length > ROLES_V5.length) { + const payload = objects[ROLES_V5.length].bytes; + extensions.push({ name: 'https://uor.foundation/extension/attestation-bundle/v1', payload, text: text(payload, 'the attestation object'), section: ROLES_V5.length }); + } + const listed = Array.isArray(holoManifest.objects) ? holoManifest.objects : []; + const expected = [1, 3, 4, 5, 6].map((index) => ({ role: ROLES_V5[index], kappa: kappa(objects[index].bytes), length: objects[index].length })); + const labelMismatches = expected + .filter((row, i) => listed[i]?.role !== row.role || listed[i]?.kappa !== row.kappa || listed[i]?.length !== row.length) + .map((row) => ({ section: ROLES_V5.indexOf(row.role), label: listed.find((l) => l.role === row.role)?.kappa ?? null, actual: row.kappa })); + if (listed.length !== expected.length) labelMismatches.push({ section: null, label: null, actual: null }); + const fingerprint = hexOf(seal); + return { + format: 5, + bytes, + body: preimage, + version: 5, + flags: 0, + sections, + manifest: { uri: MANIFEST_SCHEMA_V5, labels, section: 0 }, + holoManifest, + metadata: { text: text(objects[1].bytes, 'the source manifest'), section: 1 }, + extensions, + blobs, + footer: fingerprint, + fingerprint: sealed ? fingerprint : null, + kappa: kappa(bytes), + verification: { + footer: sealed, + seal: sealed, + labels: labelMismatches.length === 0, + labelMismatches, + }, + }; +} + function blake3HexOf(bytes) { let s = ''; for (const b of bytes) s += b.toString(16).padStart(2, '0'); @@ -209,6 +292,12 @@ function blake3HexOf(bytes) { } /** JSON with sorted keys and no whitespace, the SDK's canonical encoding (`holo/canonical.rs`). */ +/** + * The identity of a holo: for a holo v5 its κ, the `sha256:` of the file, which is also its OCI layer digest + * (ADR-017); for a legacy v4 holo the `blake3:` of its body, which its footer claims. + */ +export const holoDigest = (parsed) => (parsed.format === 5 ? parsed.kappa : `blake3:${parsed.fingerprint}`); + export function canonicalJson(value) { if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`; if (value && typeof value === 'object') { @@ -225,6 +314,7 @@ export function canonicalJson(value) { * directory and model extensions against the manifest and the blobs. */ export function resolveArchive(parsed) { + if (parsed.format === 5) return resolveArchiveV5(parsed); const extension = (name) => parsed.extensions.find((e) => e.name === name); const directoryExtension = extension(DIRECTORY_EXTENSION); const modelExtension = extension(MODEL_EXTENSION); @@ -287,3 +377,54 @@ export function resolveArchive(parsed) { }, }; } + +function resolveArchiveV5(parsed) { + const manifest = parsed.holoManifest; + const provenance = JSON.parse(parsed.extensions.find((e) => e.name === MODEL_EXTENSION).text); + const [capabilities, guest, view, model] = parsed.blobs; + const wasmLayer = manifest.layers?.find((l) => l.kind === 'wasm'); + const viewLayer = manifest.layers?.find((l) => l.kind === 'view'); + if (!wasmLayer || wasmLayer.entry !== 'holo_run') fail('archive.directory', 'the manifest has no wasm layer entered at holo_run'); + if (!viewLayer) fail('archive.directory', 'the manifest has no view layer'); + const applicationKappa = kappa(parsed.sections[0].body); + const consistent = + canonicalJson(manifest) === decoder.decode(parsed.sections[0].body) && + manifest.requires === capabilities.label && + wasmLayer.kappa === guest.label && + viewLayer.kappa === view.label && + provenance.schema === PROVENANCE_SCHEMA_V5 && + provenance.guest_content_kappa === guest.label && + provenance.model_content_kappa === model.label && + provenance.view_binding?.view_content_kappa === view.label && + provenance.application_kappa === applicationKappa && + canonicalJson(provenance) === parsed.extensions.find((e) => e.name === MODEL_EXTENSION).text; + let modelDocument; + try { + modelDocument = JSON.parse(decoder.decode(model.content)); + } catch (error) { + fail('archive.model', `model document is not JSON: ${error.message}`); + } + return { + directory: { schema_version: 5, primary_layer: 0, requires_kappa: manifest.requires, layers: manifest.layers.map((l) => ({ ...l, content_kappa: l.kappa })) }, + manifest, + provenance, + modelDocument, + guest, + view, + model, + capabilities, + identities: { + archiveFingerprint: parsed.fingerprint, + footer: parsed.footer, + archiveKappa: parsed.kappa, + basis: manifest.basis ?? null, + guestKappa: guest.label, + viewKappa: view.label, + modelKappa: model.label, + capabilitiesKappa: capabilities.label, + applicationKappa, + verified: parsed.verification.seal && parsed.verification.labels && consistent, + consistent, + }, + }; +} diff --git a/studio/shell/prism-code/src/attestations.mjs b/studio/shell/prism-code/src/attestations.mjs index ddbc19ba..8b745e92 100644 --- a/studio/shell/prism-code/src/attestations.mjs +++ b/studio/shell/prism-code/src/attestations.mjs @@ -14,6 +14,7 @@ * that is `prism verify` (#272) and `@prism-code/verify` (#273). */ import { fail } from './errors.mjs'; +import { writeObjects } from './uorc.mjs'; import { asBytes, parseArchive, KIND, MAGIC, VERSION, HEADER_LENGTH, TABLE_ENTRY_LENGTH, FOOTER_LENGTH } from './archive.mjs'; import { blake3 } from './blake3.mjs'; @@ -81,9 +82,17 @@ function splitLines(payload) { return lines; } -function digestSet(digest, where) { +function digestSet(digest, where, legacy) { if (!isObject(digest)) fail('attestation.subject', `${where} has no digest set`); const keys = Object.keys(digest).sort(); + if (!legacy) { + // A holo v5 names its objects by κ (sha256), so a subject is sha256 alone (ADR-017). + if (keys.length !== 1 || keys[0] !== 'sha256') { + fail('attestation.subject', `${where} must carry exactly sha256, the κ of the object it names (ADR-017), found ${keys.join(', ') || 'none'}`); + } + if (typeof digest.sha256 !== 'string' || !HEX64.test(digest.sha256)) fail('attestation.subject', `${where} sha256 is not 64 lowercase hex characters`); + return { sha256: digest.sha256 }; + } if (keys.length !== 2 || keys[0] !== 'blake3' || keys[1] !== 'sha256') { fail('attestation.subject', `${where} must carry exactly blake3 and sha256 (ADR-015), found ${keys.join(', ') || 'none'}`); } @@ -134,8 +143,9 @@ export function decodeBundle(line, labels = new Set()) { if (subject.name === OCI_MANIFEST_SUBJECT) { fail('attestation.subject', 'a statement inside the holo cannot name the OCI manifest; that statement is signed at push'); } - const digest = digestSet(subject.digest, where); - const label = `blake3:${digest.blake3}`; + const legacy = [...labels].some((label) => label.startsWith('blake3:')); + const digest = digestSet(subject.digest, where, legacy); + const label = legacy ? `blake3:${digest.blake3}` : `sha256:${digest.sha256}`; return { name: subject.name, digest, blob: labels.has(label) ? label : null }; }); return { @@ -225,6 +235,7 @@ function hex(bytes) { */ export function appendAttestations(source, bundles) { const parsed = parsedOf(source); + if (parsed.format !== 5) fail('attestation.format', 'a physical-v4 holo is read-only; rebuild it as a holo v5 before signing (ADR-017)'); if (!parsed.verification.footer) fail('attestation.footer', 'the archive footer does not verify; refusing to append'); if (!Array.isArray(bundles) || bundles.length === 0) fail('attestation.input', 'appendAttestations takes a non-empty array of bundles'); const existing = attestationSection(parsed); @@ -246,9 +257,8 @@ export function appendAttestations(source, bundles) { payload[line.length + at] = LF; at += line.length + 1; } - const kept = parsed.sections.filter((s) => !existing || s.index !== existing.section).map(({ kind, body }) => ({ kind, body })); - kept.push({ kind: KIND.EXTENSION, body: extensionBody(ATTESTATION_EXTENSION, payload) }); - return encodeArchive(kept, { version: parsed.version, flags: parsed.flags }); + const kept = parsed.sections.filter((s) => !existing || s.index !== existing.section).map((s) => s.body); + return writeObjects([...kept, payload]); } /** @@ -261,6 +271,7 @@ export function stripAttestations(source) { const parsed = parsedOf(source); const existing = attestationSection(parsed); if (!existing) return parsed.bytes.slice(); + if (parsed.format === 5) return writeObjects(parsed.sections.filter((s) => s.index !== existing.section).map((s) => s.body)); const kept = parsed.sections.filter((s) => s.index !== existing.section).map(({ kind, body }) => ({ kind, body })); return encodeArchive(kept, { version: parsed.version, flags: parsed.flags }); } diff --git a/studio/shell/prism-code/src/inspect.mjs b/studio/shell/prism-code/src/inspect.mjs index 0356fcbe..c52eabfc 100644 --- a/studio/shell/prism-code/src/inspect.mjs +++ b/studio/shell/prism-code/src/inspect.mjs @@ -26,7 +26,7 @@ import { import { blake3Hex } from './blake3.mjs'; import { sha256Hex } from './sha256.mjs'; import { fail } from './errors.mjs'; -import { worldOf } from './vendor/verify.mjs'; +import { inspect as inspectWithVerify, worldOf } from './vendor/verify.mjs'; export const INSPECTION_SCHEMA = 'prismpm/holo-inspection/1'; @@ -178,6 +178,8 @@ export async function inspect(source) { if (typeof Blob !== 'undefined' && source instanceof Blob) source = new Uint8Array(await source.arrayBuffer()); const bytes = asBytes(source); const parsed = parseArchive(bytes); + // A holo v5 (ADR-017) has one inspection, @prism-code/verify's, so the two packages cannot describe it differently. + if (parsed.format === 5) return inspectWithVerify(bytes); const resolved = resolveArchive(parsed); const { modelDocument, provenance, directory } = resolved; const application = modelDocument.application ?? {}; diff --git a/studio/shell/prism-code/src/provenance.mjs b/studio/shell/prism-code/src/provenance.mjs index a7009d22..e36df8f1 100644 --- a/studio/shell/prism-code/src/provenance.mjs +++ b/studio/shell/prism-code/src/provenance.mjs @@ -20,7 +20,6 @@ import { fail } from './errors.mjs'; import { asBytes, parseArchive, resolveArchive, canonicalJson } from './archive.mjs'; import { appendAttestations, readAttestations, BUNDLE_MEDIA_TYPE, STATEMENT_TYPE, DSSE_PAYLOAD_TYPE } from './attestations.mjs'; -import { blake3Hex } from './blake3.mjs'; import { sha256Hex } from './sha256.mjs'; export const PROVENANCE_PREDICATE_TYPE = 'https://slsa.dev/provenance/v1'; @@ -57,8 +56,9 @@ function base64(bytes) { return btoa(binary); } -async function dualDigest(bytes) { - return { blake3: blake3Hex(bytes), sha256: await sha256Hex(bytes) }; +/** A subject or material digest: sha256 alone, the κ of the bytes (ADR-017). */ +async function kappaDigest(bytes) { + return { sha256: await sha256Hex(bytes) }; } /** `sha256:` to hex, or a typed failure naming the lock member. */ @@ -103,7 +103,7 @@ export async function resolvedDependencies(lock) { { name: 'sdk-lock', uri: LOCK_URI, - digest: await dualDigest(bytes), + digest: await kappaDigest(bytes), mediaType: LOCK_MEDIA_TYPES[document.schema], }, { name: 'standards-lock', uri: STANDARDS_LOCK_URI, digest: { sha256: sha256Of(document.standards_lock, 'standards_lock') } }, @@ -118,7 +118,7 @@ export async function resolvedDependencies(lock) { rows.push({ name: 'world', uri: inputs.world.contract, - digest: { blake3: hexOf(inputs.world.blake3, 'inputs.world.blake3'), sha256: hexOf(inputs.world.sha256, 'inputs.world.sha256') }, + digest: { sha256: hexOf(inputs.world.sha256, 'inputs.world.sha256') }, }); } for (const [tool, version] of Object.entries(isObject(inputs.toolchain) ? inputs.toolchain : {})) { @@ -191,7 +191,7 @@ export async function provenanceStatement(source, options = {}) { const subject = []; for (const [role, blob] of blobs) { if (typeof names[role] !== 'string' || names[role].length === 0) fail('provenance.input', `subjectNames.${role} is not a path`); - subject.push({ name: names[role], digest: await dualDigest(blob.content) }); + subject.push({ name: names[role], digest: await kappaDigest(blob.content) }); } if (new Set(subject.map((s) => s.name)).size !== subject.length) fail('provenance.input', 'two subjects share a name'); @@ -201,7 +201,7 @@ export async function provenanceStatement(source, options = {}) { let version; if (lock.document.schema === 'prismpm/sdk-lock/3') { const locked = lock.document.inputs?.model; - if (!isObject(locked) || locked.blake3 !== model.blake3 || locked.sha256 !== model.sha256) { + if (!isObject(locked) || locked.sha256 !== model.sha256) { fail('provenance.lock', "the lock's inputs.model is not the model document of this archive; the lock does not describe this build"); } externalParameters.spec = lock.document.inputs.spec; diff --git a/studio/shell/prism-code/src/replay.mjs b/studio/shell/prism-code/src/replay.mjs index 07acabb5..f366c761 100644 --- a/studio/shell/prism-code/src/replay.mjs +++ b/studio/shell/prism-code/src/replay.mjs @@ -17,7 +17,6 @@ */ import { asBytes, canonicalJson, resolveArchive } from './archive.mjs'; import { STATEMENT_TYPE } from './attestations.mjs'; -import { blake3Hex } from './blake3.mjs'; import { DeterminismViolationError, ReplayError } from './errors.mjs'; import { sha256Hex } from './sha256.mjs'; import { VERSION } from './version.mjs'; @@ -56,11 +55,13 @@ function onlyMembers(value, allowed, where, schema = HISTORY_SCHEMA) { function digestSet(value, where, schema = HISTORY_SCHEMA) { if (!isObject(value)) throw invalid(`${where} is not a digest set`, schema); + // `blake3` is read only in histories recorded before holo v5 (ADR-017). onlyMembers(value, ['blake3', 'sha256'], where, schema); for (const key of ['blake3', 'sha256']) { + if (key === 'blake3' && !Object.hasOwn(value, key)) continue; if (typeof value[key] !== 'string' || !HEX64.test(value[key])) throw invalid(`${where}.${key} is not 64 lowercase hex characters`, schema); } - return { blake3: value.blake3, sha256: value.sha256 }; + return Object.hasOwn(value, 'blake3') ? { blake3: value.blake3, sha256: value.sha256 } : { sha256: value.sha256 }; } function hexField(value, where, schema = HISTORY_SCHEMA) { @@ -179,11 +180,12 @@ export function historyBytes(history) { return encoder.encode(canonicalJson(parseHistory(history))); } +/** The digest set of `bytes`: its sha256, the κ (ADR-017). */ async function digestsOf(bytes) { - return { blake3: blake3Hex(bytes), sha256: await sha256Hex(bytes) }; + return { sha256: await sha256Hex(bytes) }; } -/** Both digests of a history, as `prism/replay/v1` names it (ADR-015). */ +/** The digest set of a history, as `prism/replay/v1` names it (ADR-017). */ export function historyDigest(history) { return digestsOf(historyBytes(history)); } @@ -417,7 +419,7 @@ export async function experimental_replay(app, histories, options = {}) { if (!app.identities?.verified) throw new ReplayError('the archive fails its own integrity checks; a replay of it would prove nothing', { check: 'replay.holo' }); const parsed = list.map(parseHistory); const digests = await Promise.all(parsed.map(historyDigest)); - if (new Set(digests.map((d) => d.blake3)).size !== digests.length) throw new ReplayError('the same history was given twice; the statement names each one once', { check: 'replay.history' }); + if (new Set(digests.map((d) => d.sha256)).size !== digests.length) throw new ReplayError('the same history was given twice; the statement names each one once', { check: 'replay.history' }); const session = Boolean(app.world?.session); for (const history of parsed) { diff --git a/studio/shell/prism-code/src/uorc.mjs b/studio/shell/prism-code/src/uorc.mjs new file mode 100644 index 00000000..5113009b --- /dev/null +++ b/studio/shell/prism-code/src/uorc.mjs @@ -0,0 +1,159 @@ +/** + * Holo v5 container: a self-contained raw UORC archive of ordered objects + * (ADR-017; UOR-Foundation/compression `Uorc.Codec.Archive`, what + * `uorc::archive::raw_objects` writes). The Rust twin is + * `crates/prismpm/src/holo/v5.rs`; both are held to the same bytes. + * + * "UORC" 02 01 00 00 uleb(count) uleb(length)* uleb(bodyLength) body seal[32] + * + * `seal` is UORC-SHA256-CHAIN-v1 over every byte before it. Every identity is + * a κ-label: `sha256:` and the lowercase hex SHA-256 of the bytes it names. + */ +import { DigestMismatchError, fail } from './errors.mjs'; +import { sha256HexSync } from './sha256.mjs'; + +export const MAGIC = Uint8Array.of(0x55, 0x4f, 0x52, 0x43, 0x02, 0x01); +export const SEAL_LENGTH = 32; +export const KAPPA_LENGTH = 71; +/** The decode budget every reader applies to an application holo. */ +export const APPLICATION_BUDGET = Object.freeze({ objects: 16, bytes: 2 ** 30 }); + +const TAG = new TextEncoder().encode('UORC-SHA256-CHAIN-v1\0'); + +function fromHex(hex) { + const out = new Uint8Array(hex.length / 2); + for (let i = 0; i < out.length; i += 1) out[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16); + return out; +} + +function concat(parts) { + const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)); + let at = 0; + for (const part of parts) { + out.set(part, at); + at += part.length; + } + return out; +} + +const sha256 = (parts) => fromHex(sha256HexSync(concat(parts))); + +/** The κ-label of `bytes`. */ +export function kappa(bytes) { + return `sha256:${sha256HexSync(bytes)}`; +} + +/** Whether `label` is a well-formed κ-label. */ +export function isKappa(label) { + return typeof label === 'string' && /^sha256:[0-9a-f]{64}$/.test(label); +} + +/** Whether `bytes` start like a UORC archive. */ +export function isUorc(bytes) { + return bytes.length >= 4 && bytes[0] === 0x55 && bytes[1] === 0x4f && bytes[2] === 0x52 && bytes[3] === 0x43; +} + +/** UORC-SHA256-CHAIN-v1 of `preimage`, as bytes. */ +export function chain(preimage) { + let c = sha256([TAG, Uint8Array.of(0)]); + const whole = preimage.length - (preimage.length % 64); + for (let at = 0; at < whole; at += 64) c = sha256([TAG, Uint8Array.of(1), c, preimage.subarray(at, at + 64)]); + const tail = preimage.subarray(whole); + return sha256([TAG, Uint8Array.of(2), c, Uint8Array.of(tail.length), tail]); +} + +function uleb(n) { + const out = []; + while (n >= 0x80) { + out.push((n % 0x80) | 0x80); + n = Math.floor(n / 0x80); + } + out.push(n); + return Uint8Array.from(out); +} + +function readUleb(bytes, at) { + let value = 0; + let scale = 1; + const start = at; + for (;;) { + if (at >= bytes.length || at - start > 7) return null; + const byte = bytes[at]; + at += 1; + value += (byte & 0x7f) * scale; + scale *= 0x80; + if (byte < 0x80) { + if (byte === 0 && at - start > 1) return null; // not the shortest form + if (!Number.isSafeInteger(value)) return null; + return [value, at]; + } + } +} + +/** The self-contained raw UORC archive of `objects`, in order. */ +export function writeObjects(objects) { + const header = [MAGIC, Uint8Array.of(0, 0), uleb(objects.length)]; + for (const object of objects) header.push(uleb(object.length)); + header.push(uleb(objects.reduce((n, o) => n + o.length, 0))); + const preimage = concat([...header, ...objects]); + return concat([preimage, chain(preimage)]); +} + +function equal(a, b) { + if (a.length !== b.length) return false; + for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false; + return true; +} + +/** + * The ordered objects of a raw self-contained UORC archive and whether its + * seal matches. The framing and the budget are enforced; the seal is reported, + * so `inspect` can still look at a damaged holo. + */ +export function layout(bytes, budget = APPLICATION_BUDGET) { + if (!equal(bytes.subarray(0, 6), MAGIC)) fail('archive.magic', 'a holo v5 file is a UORC archive (format 2, profile 1)'); + if (bytes.length < 8 + SEAL_LENGTH) fail('archive.bounds', 'UORC archive is truncated'); + const preimage = bytes.subarray(0, bytes.length - SEAL_LENGTH); + const seal = bytes.subarray(bytes.length - SEAL_LENGTH); + const sealed = equal(chain(preimage), seal); + if (preimage[6] !== 0 || preimage[7] !== 0) fail('archive.bounds', 'a holo is a self-contained archive whose objects are stored raw'); + let read = readUleb(preimage, 8); + if (!read) fail('archive.bounds', 'object count is not a ULEB128'); + const [count] = read; + let at = read[1]; + if (count === 0 || count > budget.objects) fail('archive.bounds', `archive declares ${count} objects; a holo holds 1 to ${budget.objects}`); + const lengths = []; + let total = 0; + for (let i = 0; i < count; i += 1) { + read = readUleb(preimage, at); + if (!read) fail('archive.bounds', 'object length is not a ULEB128'); + total += read[0]; + if (total > budget.bytes) fail('archive.bounds', 'archive exceeds the decode budget'); + lengths.push(read[0]); + at = read[1]; + } + read = readUleb(preimage, at); + if (!read) fail('archive.bounds', 'body length is not a ULEB128'); + const [bodyLength, start] = read; + if (bodyLength !== total || preimage.length - start !== total) { + fail('archive.bounds', 'body length disagrees with the objects or the archive has trailing bytes'); + } + const objects = []; + let offset = start; + for (const length of lengths) { + objects.push({ offset, length, bytes: preimage.subarray(offset, offset + length) }); + offset += length; + } + return { objects, sealed, seal, preimage }; +} + +/** The ordered objects of a UORC archive whose seal matches; anything else throws. */ +export function readObjects(bytes, budget = APPLICATION_BUDGET) { + if (equal(bytes.subarray(0, 6), MAGIC) && bytes.length >= SEAL_LENGTH) { + const preimage = bytes.subarray(0, bytes.length - SEAL_LENGTH); + if (!equal(chain(preimage), bytes.subarray(bytes.length - SEAL_LENGTH))) { + throw new DigestMismatchError('integrity failure: the holo was altered: its UORC-SHA256-CHAIN-v1 seal does not match', { check: 'holo.integrity' }); + } + } + return layout(bytes, budget).objects.map((object) => object.bytes); +} diff --git a/studio/shell/prism-code/src/vendor/verify.mjs b/studio/shell/prism-code/src/vendor/verify.mjs index 2a6c19c3..8587a944 100644 --- a/studio/shell/prism-code/src/vendor/verify.mjs +++ b/studio/shell/prism-code/src/vendor/verify.mjs @@ -315,6 +315,21 @@ const __vendor_spec = (() => { ]), }), }); + /** + * Holo v5 (ADR-017): a raw self-contained UORC archive of ordered objects, + * sealed by UORC-SHA256-CHAIN-v1. Every identity is a κ-label, `sha256:` and + * the hex SHA-256 of the bytes it names; the κ of the file is its OCI digest. + */ + const HOLO_V5 = freeze({ + /** "UORC", format 2, profile 1, scope 0 (self-contained), representation 0 (raw). */ + MAGIC_HEX: '554f52430201', + MANIFEST_SCHEMA: 'prism/holo/5', + PROVENANCE_SCHEMA: 'prismpm/model-provenance/2', + /** The objects in archive order; `attestations` follows only when the holo is signed. */ + ROLES: freeze(['manifest', 'source-manifest', 'provenance', 'capabilities', 'guest', 'view', 'model']), + ROLE_ATTESTATIONS: 'attestations', + KAPPA_PREFIX: 'sha256:', + }); /** * Build provenance of a holo, issue #268 (docs/proposals/268-build-provenance.md). The predicate is SLSA * provenance v1; Prism adds the build type and the rules for each member. Schema: SCHEMA. @@ -383,6 +398,7 @@ const __vendor_spec = (() => { "prismpm/model-document/5": "schemas/documents/model-document-v5.schema.json", "prismpm/model-document/6": "schemas/documents/model-document-v6.schema.json", "prismpm/model-provenance/1": "schemas/documents/model-provenance-v1.schema.json", + "prismpm/model-provenance/2": "schemas/documents/model-provenance-v2.schema.json", }); /** The holo sections this reader checks. The spec's HOLO_SCHEMAS lists every section schema. */ @@ -392,7 +408,7 @@ const __vendor_spec = (() => { "SOURCE_MANIFEST": "schemas/holo/source-manifest.schema.json", "APPLICATION_DIRECTORY": "schemas/holo/application-directory.schema.json", }); - return Object.freeze({ FORMAT_REVISION, MAGIC, PHYSICAL_VERSION, FLAGS, HEADER_LENGTH, TABLE_ENTRY_LENGTH, SECTION_COUNT, BODY_OFFSET, FOOTER_LENGTH, SECTION_KIND, SECTION_ORDER, LABEL_PREFIX, LABEL_LENGTH, APP_MANIFEST, CAPABILITY_SET, EXTENSION, CORE_WASM, CORE_WASM_SESSION, WORLDS, HOLOVIEW, ATTESTATION, ATTESTATION_BUNDLE, OCI, FORMAT_REVISIONS, PROVENANCE, POLICY, ASSURANCE, SCHEMAS, HOLO_SCHEMAS }); + return Object.freeze({ FORMAT_REVISION, MAGIC, PHYSICAL_VERSION, FLAGS, HEADER_LENGTH, TABLE_ENTRY_LENGTH, SECTION_COUNT, BODY_OFFSET, FOOTER_LENGTH, SECTION_KIND, SECTION_ORDER, LABEL_PREFIX, LABEL_LENGTH, APP_MANIFEST, CAPABILITY_SET, EXTENSION, CORE_WASM, CORE_WASM_SESSION, WORLDS, HOLOVIEW, ATTESTATION, ATTESTATION_BUNDLE, OCI, FORMAT_REVISIONS, HOLO_V5, PROVENANCE, POLICY, ASSURANCE, SCHEMAS, HOLO_SCHEMAS }); })(); // src/vendor/blake3.mjs @@ -816,6 +832,7 @@ const __vendor_schemas = (() => { "schemas/documents/model-document-v5.schema.json": {"$id":"prismpm/model-document/5","$schema":"https://json-schema.org/draft/2020-12/schema","title":"BoundedTextModelDocument","type":"object","additionalProperties":false,"properties":{"application":{"$ref":"#/$defs/application"},"architecture":{"$ref":"#/$defs/architecture"},"provenance":{"$ref":"#/$defs/provenance"},"quality":{"$ref":"#/$defs/quality"},"schema":{"const":"prismpm/model-document/5"},"security":{"$ref":"#/$defs/security"},"standards_profile":{"oneOf":[{"const":[]},{"const":["ISO-25010-2023","ISO-27005-2022","ISO-27034-1-2011","ISO-27034-5-2017","ISO-42010-2022"]}]}},"required":["application","architecture","provenance","quality","schema","security","standards_profile"],"$defs":{"application":{"type":"object","additionalProperties":false,"properties":{"profile":{"const":"prismpm/text-application/2"},"name":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9_. -]*[A-Za-z0-9_-])?$"},"cargo_name":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"cargo_version":{"pattern":"^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$","type":"string"},"cargo_description":{"minLength":1,"type":"string"},"cargo_repository":{"format":"uri","pattern":"^https://","type":"string"},"cargo_homepage":{"format":"uri","pattern":"^https://","type":"string"},"library_roots":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$"}},"acceptance_vectors":{"items":{"$ref":"#/$defs/application_acceptance_vector"},"minItems":1,"type":"array"},"entry_root":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$"},"core_contract":{"const":"hologram:guest/core-wasm@1"},"request_maximum":{"maximum":4294967295,"minimum":1,"type":"integer"},"response_maximum":{"maximum":4294967295,"minimum":1,"type":"integer"},"guest_allocation_maximum":{"maximum":4294967295,"minimum":1,"type":"integer"},"capabilities_empty":{"const":true},"fat_archive":{"const":true},"primary_layer":{"const":0},"view_layer":{"const":1},"view":{"$ref":"#/$defs/text_view"},"core_memory_pages":{"maximum":32767,"minimum":1,"type":"integer"},"core_stack_bytes":{"maximum":4294967295,"minimum":16,"multipleOf":16,"type":"integer"}},"required":["acceptance_vectors","capabilities_empty","cargo_description","cargo_homepage","cargo_name","cargo_repository","cargo_version","core_contract","core_memory_pages","core_stack_bytes","entry_root","fat_archive","guest_allocation_maximum","library_roots","name","primary_layer","profile","request_maximum","response_maximum","view","view_layer"]},"application_acceptance_vector":{"additionalProperties":false,"properties":{"request":{"items":{"maximum":255,"minimum":0,"type":"integer"},"type":"array"},"response":{"items":{"maximum":255,"minimum":0,"type":"integer"},"type":"array"}},"required":["request","response"],"type":"object"},"provenance":{"additionalProperties":false,"properties":{"compiler_semantics_id":{"$ref":"#/$defs/sha256"},"emitter_semantics_id":{"$ref":"#/$defs/sha256"},"facet_packages":{"items":{"$ref":"#/$defs/facet"},"maxItems":3,"type":"array"},"semantic_id":{"$ref":"#/$defs/sha256"},"snapshot_id":{"$ref":"#/$defs/sha256"},"source_id":{"$ref":"#/$defs/sha256"}},"required":["compiler_semantics_id","emitter_semantics_id","facet_packages","semantic_id","snapshot_id","source_id"],"type":"object"},"sha256":{"pattern":"^[0-9a-f]{64}$","type":"string"},"text_view":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"heading":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"input_label":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"submit_label":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"output_label":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"input_error":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"response_error":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"}},"required":["title","heading","input_label","submit_label","output_label","input_error","response_error"]},"activity":{"additionalProperties":false,"properties":{"control_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"}},"required":["control_index","id","index"],"type":"object"},"architecture":{"additionalProperties":false,"properties":{"component_kinds":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"components":{"items":{"$ref":"#/$defs/component"},"type":"array"},"concerns":{"items":{"$ref":"#/$defs/described"},"type":"array"},"edge_kinds":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"edges":{"items":{"$ref":"#/$defs/edge"},"type":"array"},"model_kinds":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"stakeholders":{"items":{"$ref":"#/$defs/described"},"type":"array"},"viewpoints":{"items":{"$ref":"#/$defs/viewpoint"},"type":"array"},"views":{"items":{"$ref":"#/$defs/view"},"type":"array"}},"required":["component_kinds","components","concerns","edge_kinds","edges","model_kinds","stakeholders","viewpoints","views"],"type":"object"},"asset":{"additionalProperties":false,"properties":{"component_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"}},"required":["component_index","id","index"],"type":"object"},"catalog":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_catalog"},"index":{"$ref":"#/$defs/index"}},"required":["id","index"],"type":"object"},"component":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"kind_id":{"$ref":"#/$defs/qualified_catalog"},"name":{"type":"string","maxLength":256,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*$"},"text":{"type":"string","maxLength":4096,"pattern":"^[^\\u0000-\\u0009\\u000b-\\u001f\\u007f-\\u009f]*$"}},"required":["id","index","kind_id"],"type":"object"},"control":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"risk_index":{"$ref":"#/$defs/index"}},"required":["id","index","risk_index"],"type":"object"},"described":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"name":{"type":"string","maxLength":256,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*$"},"text":{"type":"string","maxLength":4096,"pattern":"^[^\\u0000-\\u0009\\u000b-\\u001f\\u007f-\\u009f]*$"}},"required":["id","index"]},"edge":{"additionalProperties":false,"properties":{"from_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"kind_id":{"$ref":"#/$defs/qualified_catalog"},"to_index":{"$ref":"#/$defs/index"}},"required":["from_index","id","index","kind_id","to_index"],"type":"object"},"facet":{"additionalProperties":false,"properties":{"content_id":{"$ref":"#/$defs/sha256"},"package":{"enum":["prism.arch","prism.qual","prism.sec"]},"version":{"const":"1.0.0"}},"required":["content_id","package","version"],"type":"object"},"index":{"maximum":18446744073709552000,"minimum":0,"type":"integer"},"indexed":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"}},"required":["id","index"],"type":"object"},"measure":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"requirement_index":{"$ref":"#/$defs/index"},"threshold":{"$ref":"#/$defs/index"}},"required":["id","index","requirement_index","threshold"],"type":"object"},"measurement":{"additionalProperties":false,"properties":{"control_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"passed":{"type":"boolean"}},"required":["control_index","id","index","passed"],"type":"object"},"qualified_catalog":{"pattern":"^prism\\.(arch|qual|sec)@1\\.0\\.0::[A-Za-z][A-Za-z0-9_]*\\.[A-Za-z][A-Za-z0-9_]*$","type":"string"},"qualified_entity":{"pattern":"^[A-Za-z][A-Za-z0-9_.]*::[A-Za-z][A-Za-z0-9_]*$","type":"string"},"quality":{"additionalProperties":false,"properties":{"characteristics":{"items":{"$ref":"#/$defs/indexed"},"type":"array"},"measures":{"items":{"$ref":"#/$defs/measure"},"type":"array"},"requirements":{"items":{"$ref":"#/$defs/requirement"},"type":"array"},"subcharacteristics":{"items":{"$ref":"#/$defs/subcharacteristic"},"type":"array"}},"required":["characteristics","measures","requirements","subcharacteristics"],"type":"object"},"requirement":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"subcharacteristic_index":{"$ref":"#/$defs/index"}},"required":["id","index","subcharacteristic_index"],"type":"object"},"risk":{"additionalProperties":false,"properties":{"asset_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"impact_id":{"$ref":"#/$defs/qualified_catalog"},"index":{"$ref":"#/$defs/index"},"likelihood_id":{"$ref":"#/$defs/qualified_catalog"},"threat_index":{"$ref":"#/$defs/index"}},"required":["asset_index","id","impact_id","index","likelihood_id","threat_index"],"type":"object"},"security":{"additionalProperties":false,"properties":{"activities":{"items":{"$ref":"#/$defs/activity"},"type":"array"},"assets":{"items":{"$ref":"#/$defs/asset"},"type":"array"},"controls":{"items":{"$ref":"#/$defs/control"},"type":"array"},"impacts":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"likelihoods":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"measurements":{"items":{"$ref":"#/$defs/measurement"},"type":"array"},"risks":{"items":{"$ref":"#/$defs/risk"},"type":"array"},"threats":{"items":{"$ref":"#/$defs/indexed"},"type":"array"}},"required":["activities","assets","controls","impacts","likelihoods","measurements","risks","threats"],"type":"object"},"subcharacteristic":{"additionalProperties":false,"properties":{"characteristic_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"}},"required":["characteristic_index","id","index"],"type":"object"},"view":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"model_kind_index":{"$ref":"#/$defs/index"},"viewpoint_index":{"$ref":"#/$defs/index"}},"required":["id","index","model_kind_index","viewpoint_index"],"type":"object"},"viewpoint":{"additionalProperties":false,"properties":{"concern_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"model_kind_index":{"$ref":"#/$defs/index"},"stakeholder_index":{"$ref":"#/$defs/index"}},"required":["concern_index","id","index","model_kind_index","stakeholder_index"],"type":"object"}}}, "schemas/documents/model-document-v6.schema.json": {"$id":"prismpm/model-document/6","$schema":"https://json-schema.org/draft/2020-12/schema","title":"BoundedTextCommandModelDocument","type":"object","additionalProperties":false,"properties":{"application":{"$ref":"#/$defs/application"},"architecture":{"$ref":"#/$defs/architecture"},"provenance":{"$ref":"#/$defs/provenance"},"quality":{"$ref":"#/$defs/quality"},"schema":{"const":"prismpm/model-document/6"},"security":{"$ref":"#/$defs/security"},"standards_profile":{"oneOf":[{"const":[]},{"const":["ISO-25010-2023","ISO-27005-2022","ISO-27034-1-2011","ISO-27034-5-2017","ISO-42010-2022"]}]}},"required":["application","architecture","provenance","quality","schema","security","standards_profile"],"$defs":{"application":{"type":"object","additionalProperties":false,"properties":{"profile":{"const":"prismpm/text-application/3"},"name":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9](?:[A-Za-z0-9_. -]*[A-Za-z0-9_-])?$"},"cargo_name":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"cargo_version":{"pattern":"^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$","type":"string"},"cargo_description":{"minLength":1,"type":"string"},"cargo_repository":{"format":"uri","pattern":"^https://","type":"string"},"cargo_homepage":{"format":"uri","pattern":"^https://","type":"string"},"library_roots":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$"}},"acceptance_vectors":{"items":{"$ref":"#/$defs/application_acceptance_vector"},"minItems":1,"type":"array"},"entry_root":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$"},"core_contract":{"const":"hologram:guest/core-wasm@1"},"request_maximum":{"maximum":4294967295,"minimum":1,"type":"integer"},"response_maximum":{"maximum":4294967295,"minimum":1,"type":"integer"},"guest_allocation_maximum":{"maximum":4294967295,"minimum":1,"type":"integer"},"capabilities_empty":{"const":true},"fat_archive":{"const":true},"primary_layer":{"const":0},"view_layer":{"const":1},"view":{"$ref":"#/$defs/text_view"},"core_memory_pages":{"maximum":32767,"minimum":1,"type":"integer","description":"Absent means the V1 implicit budget of 32 pages."},"core_stack_bytes":{"maximum":4294967295,"minimum":16,"multipleOf":16,"type":"integer","description":"Absent means the V1 implicit budget of 65536 bytes."},"cli":{"$ref":"#/$defs/text_cli"},"workbench":{"$ref":"#/$defs/WorkbenchView"}},"required":["acceptance_vectors","capabilities_empty","cargo_description","cargo_homepage","cargo_name","cargo_repository","cargo_version","cli","core_contract","entry_root","fat_archive","guest_allocation_maximum","library_roots","name","primary_layer","profile","request_maximum","response_maximum","view","view_layer"]},"application_acceptance_vector":{"additionalProperties":false,"properties":{"request":{"items":{"maximum":255,"minimum":0,"type":"integer"},"type":"array"},"response":{"items":{"maximum":255,"minimum":0,"type":"integer"},"type":"array"}},"required":["request","response"],"type":"object"},"provenance":{"additionalProperties":false,"properties":{"compiler_semantics_id":{"$ref":"#/$defs/sha256"},"emitter_semantics_id":{"$ref":"#/$defs/sha256"},"facet_packages":{"items":{"$ref":"#/$defs/facet"},"maxItems":3,"type":"array"},"semantic_id":{"$ref":"#/$defs/sha256"},"snapshot_id":{"$ref":"#/$defs/sha256"},"source_id":{"$ref":"#/$defs/sha256"}},"required":["compiler_semantics_id","emitter_semantics_id","facet_packages","semantic_id","snapshot_id","source_id"],"type":"object"},"sha256":{"pattern":"^[0-9a-f]{64}$","type":"string"},"text_view":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"heading":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"input_label":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"submit_label":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"output_label":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"input_error":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"response_error":{"type":"string","minLength":1,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"}},"required":["title","heading","input_label","submit_label","output_label","input_error","response_error"]},"text_cli":{"type":"object","additionalProperties":false,"properties":{"command":{"type":"string","pattern":"^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$","not":{"const":"examples"}},"description":{"type":"string","minLength":1,"maxLength":16384,"pattern":"^[^\\u0000-\\u0009\\u000b-\\u001f\\u007f-\\u009f]+$"},"usage_code":{"type":"integer","minimum":0,"maximum":125},"io_code":{"type":"integer","minimum":0,"maximum":125},"limit_code":{"type":"integer","minimum":0,"maximum":125,"description":"Exit code of a request refused over the request maximum. Absent means the code of the error outcome."},"outcomes":{"type":"array","minItems":1,"maxItems":16,"items":{"$ref":"#/$defs/text_cli_outcome"}},"sections":{"type":"array","maxItems":32,"items":{"$ref":"#/$defs/text_cli_section"}},"examples":{"type":"array","maxItems":64,"items":{"$ref":"#/$defs/text_cli_example"}}},"required":["command","description","examples","io_code","outcomes","sections","usage_code"]},"text_cli_outcome":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","pattern":"^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$"},"prefix":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[^\\u0000]+$"},"exit_code":{"type":"integer","minimum":0,"maximum":125}},"required":["exit_code","name","prefix"]},"text_cli_section":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"maxLength":16384,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]+$"},"body":{"type":"string","minLength":1,"maxLength":16384,"pattern":"^[^\\u0000-\\u0009\\u000b-\\u001f\\u007f-\\u009f]+$"}},"required":["body","title"]},"text_cli_example":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","pattern":"^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$"},"text":{"type":"string","minLength":1,"maxLength":16384,"pattern":"^[^\\u0000]+$"}},"required":["name","text"]},"activity":{"additionalProperties":false,"properties":{"control_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"}},"required":["control_index","id","index"],"type":"object"},"architecture":{"additionalProperties":false,"properties":{"component_kinds":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"components":{"items":{"$ref":"#/$defs/component"},"type":"array"},"concerns":{"items":{"$ref":"#/$defs/described"},"type":"array"},"edge_kinds":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"edges":{"items":{"$ref":"#/$defs/edge"},"type":"array"},"model_kinds":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"stakeholders":{"items":{"$ref":"#/$defs/described"},"type":"array"},"viewpoints":{"items":{"$ref":"#/$defs/viewpoint"},"type":"array"},"views":{"items":{"$ref":"#/$defs/view"},"type":"array"}},"required":["component_kinds","components","concerns","edge_kinds","edges","model_kinds","stakeholders","viewpoints","views"],"type":"object"},"asset":{"additionalProperties":false,"properties":{"component_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"}},"required":["component_index","id","index"],"type":"object"},"catalog":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_catalog"},"index":{"$ref":"#/$defs/index"}},"required":["id","index"],"type":"object"},"component":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"kind_id":{"$ref":"#/$defs/qualified_catalog"},"name":{"type":"string","maxLength":256,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*$"},"text":{"type":"string","maxLength":4096,"pattern":"^[^\\u0000-\\u0009\\u000b-\\u001f\\u007f-\\u009f]*$"}},"required":["id","index","kind_id"],"type":"object"},"control":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"risk_index":{"$ref":"#/$defs/index"}},"required":["id","index","risk_index"],"type":"object"},"described":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"name":{"type":"string","maxLength":256,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*$"},"text":{"type":"string","maxLength":4096,"pattern":"^[^\\u0000-\\u0009\\u000b-\\u001f\\u007f-\\u009f]*$"}},"required":["id","index"]},"edge":{"additionalProperties":false,"properties":{"from_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"kind_id":{"$ref":"#/$defs/qualified_catalog"},"to_index":{"$ref":"#/$defs/index"}},"required":["from_index","id","index","kind_id","to_index"],"type":"object"},"facet":{"additionalProperties":false,"properties":{"content_id":{"$ref":"#/$defs/sha256"},"package":{"enum":["prism.arch","prism.qual","prism.sec"]},"version":{"const":"1.0.0"}},"required":["content_id","package","version"],"type":"object"},"index":{"maximum":18446744073709552000,"minimum":0,"type":"integer"},"indexed":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"}},"required":["id","index"],"type":"object"},"measure":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"requirement_index":{"$ref":"#/$defs/index"},"threshold":{"$ref":"#/$defs/index"}},"required":["id","index","requirement_index","threshold"],"type":"object"},"measurement":{"additionalProperties":false,"properties":{"control_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"passed":{"type":"boolean"}},"required":["control_index","id","index","passed"],"type":"object"},"qualified_catalog":{"pattern":"^prism\\.(arch|qual|sec)@1\\.0\\.0::[A-Za-z][A-Za-z0-9_]*\\.[A-Za-z][A-Za-z0-9_]*$","type":"string"},"qualified_entity":{"pattern":"^[A-Za-z][A-Za-z0-9_.]*::[A-Za-z][A-Za-z0-9_]*$","type":"string"},"quality":{"additionalProperties":false,"properties":{"characteristics":{"items":{"$ref":"#/$defs/indexed"},"type":"array"},"measures":{"items":{"$ref":"#/$defs/measure"},"type":"array"},"requirements":{"items":{"$ref":"#/$defs/requirement"},"type":"array"},"subcharacteristics":{"items":{"$ref":"#/$defs/subcharacteristic"},"type":"array"}},"required":["characteristics","measures","requirements","subcharacteristics"],"type":"object"},"requirement":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"subcharacteristic_index":{"$ref":"#/$defs/index"}},"required":["id","index","subcharacteristic_index"],"type":"object"},"risk":{"additionalProperties":false,"properties":{"asset_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"impact_id":{"$ref":"#/$defs/qualified_catalog"},"index":{"$ref":"#/$defs/index"},"likelihood_id":{"$ref":"#/$defs/qualified_catalog"},"threat_index":{"$ref":"#/$defs/index"}},"required":["asset_index","id","impact_id","index","likelihood_id","threat_index"],"type":"object"},"security":{"additionalProperties":false,"properties":{"activities":{"items":{"$ref":"#/$defs/activity"},"type":"array"},"assets":{"items":{"$ref":"#/$defs/asset"},"type":"array"},"controls":{"items":{"$ref":"#/$defs/control"},"type":"array"},"impacts":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"likelihoods":{"items":{"$ref":"#/$defs/catalog"},"type":"array"},"measurements":{"items":{"$ref":"#/$defs/measurement"},"type":"array"},"risks":{"items":{"$ref":"#/$defs/risk"},"type":"array"},"threats":{"items":{"$ref":"#/$defs/indexed"},"type":"array"}},"required":["activities","assets","controls","impacts","likelihoods","measurements","risks","threats"],"type":"object"},"subcharacteristic":{"additionalProperties":false,"properties":{"characteristic_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"}},"required":["characteristic_index","id","index"],"type":"object"},"view":{"additionalProperties":false,"properties":{"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"model_kind_index":{"$ref":"#/$defs/index"},"viewpoint_index":{"$ref":"#/$defs/index"}},"required":["id","index","model_kind_index","viewpoint_index"],"type":"object"},"viewpoint":{"additionalProperties":false,"properties":{"concern_index":{"$ref":"#/$defs/index"},"id":{"$ref":"#/$defs/qualified_entity"},"index":{"$ref":"#/$defs/index"},"model_kind_index":{"$ref":"#/$defs/index"},"stakeholder_index":{"$ref":"#/$defs/index"}},"required":["concern_index","id","index","model_kind_index","stakeholder_index"],"type":"object"},"Choice":{"type":"object","additionalProperties":false,"properties":{"value":{"type":"string","maxLength":1048576},"label":{"type":"string","maxLength":1048576}},"required":["value","label"]},"Field":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":1048576},"label":{"type":"string","maxLength":1048576},"kind":{"enum":["text","multiline","natural","choice"]},"help":{"type":"string","maxLength":1048576},"placeholder":{"type":"string","maxLength":1048576},"initial_value":{"type":"string","maxLength":1048576},"required":{"type":"boolean"},"choices":{"type":"array","maxItems":4096,"items":{"$ref":"#/$defs/Choice"}}},"required":["id","label","kind","help","placeholder","initial_value","required","choices"]},"Example":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":1048576},"label":{"type":"string","maxLength":1048576},"description":{"type":"string","maxLength":1048576},"values":{"type":"array","maxItems":4096,"items":{"type":"string","maxLength":1048576}},"expected_response":{"type":"string","maxLength":1048576},"explanation":{"type":"string","maxLength":1048576}},"required":["id","label","description","values","expected_response","explanation"]},"Operation":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":1048576},"label":{"type":"string","maxLength":1048576},"summary":{"type":"string","maxLength":1048576},"help":{"type":"string","maxLength":1048576},"request_prefix":{"type":"string","maxLength":1048576},"fields":{"type":"array","maxItems":4096,"items":{"$ref":"#/$defs/Field"}},"examples":{"type":"array","maxItems":4096,"items":{"$ref":"#/$defs/Example"}}},"required":["id","label","summary","help","request_prefix","fields","examples"]},"Section":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","maxLength":1048576},"title":{"type":"string","maxLength":1048576},"paragraphs":{"type":"array","maxItems":4096,"items":{"type":"string","maxLength":1048576}}},"required":["id","title","paragraphs"]},"Link":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string","maxLength":1048576},"https_url":{"type":"string","maxLength":1048576}},"required":["label","https_url"]},"ErrorHint":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","maxLength":1048576},"title":{"type":"string","maxLength":1048576},"explanation":{"type":"string","maxLength":1048576},"recovery":{"type":"string","maxLength":1048576},"fields":{"type":"array","maxItems":4096,"items":{"type":"string","maxLength":1048576}}},"required":["code","title","explanation","recovery","fields"]},"StatusCopy":{"type":"object","additionalProperties":false,"properties":{"initializing":{"type":"string","maxLength":1048576},"ready":{"type":"string","maxLength":1048576},"running":{"type":"string","maxLength":1048576},"cancelling":{"type":"string","maxLength":1048576},"cancelled":{"type":"string","maxLength":1048576},"timeout":{"type":"string","maxLength":1048576},"load_error":{"type":"string","maxLength":1048576},"compute_error":{"type":"string","maxLength":1048576},"input_error":{"type":"string","maxLength":1048576},"response_error":{"type":"string","maxLength":1048576},"script_required":{"type":"string","maxLength":16384}},"required":["initializing","ready","running","cancelling","cancelled","timeout","load_error","compute_error","input_error","response_error","script_required"]},"Design":{"type":"object","additionalProperties":false,"properties":{"palette":{"enum":["indigo","ocean"]},"density":{"enum":["comfortable","compact"]},"width":{"enum":["balanced","wide"]},"color_scheme":{"enum":["system","light","dark"]}},"required":["palette","density","width","color_scheme"]},"RawEditor":{"type":"object","additionalProperties":false,"properties":{"request_prefix":{"type":"string","maxLength":1048576},"label":{"type":"string","maxLength":1048576},"help":{"type":"string","maxLength":1048576},"placeholder":{"type":"string","maxLength":1048576},"initial_value":{"type":"string","maxLength":1048576},"submit_label":{"type":"string","maxLength":1048576},"response_label":{"type":"string","maxLength":1048576},"expanded":{"type":"boolean"}},"required":["request_prefix","label","help","placeholder","initial_value","submit_label","response_label","expanded"]},"DisplaySpec":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":1048576},"empty_text":{"type":"string","maxLength":1048576},"raw_label":{"type":"string","maxLength":1048576},"maximum_cells":{"type":"integer","minimum":0,"maximum":4294967295},"maximum_details":{"type":"integer","minimum":0,"maximum":4294967295}},"required":["title","empty_text","raw_label","maximum_cells","maximum_details"]},"Execution":{"type":"object","additionalProperties":false,"properties":{"timeout_milliseconds":{"type":"integer","minimum":0,"maximum":4294967295},"cancel_label":{"type":"string","maxLength":1048576},"retry_label":{"type":"string","maxLength":1048576},"wasm_cache_policy":{"type":"string","enum":["no-store"]}},"required":["timeout_milliseconds","cancel_label","retry_label","wasm_cache_policy"]},"WorkbenchView":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":1048576},"heading":{"type":"string","maxLength":1048576},"purpose":{"type":"string","maxLength":1048576},"audience":{"type":"string","maxLength":1048576},"guidance":{"type":"array","maxItems":4096,"items":{"type":"string","maxLength":1048576}},"initial_operation":{"type":"string","maxLength":1048576},"initial_example":{"type":"string","maxLength":1048576},"operations":{"type":"array","maxItems":4096,"items":{"$ref":"#/$defs/Operation"}},"sections":{"type":"array","maxItems":4096,"items":{"$ref":"#/$defs/Section"}},"links":{"type":"array","maxItems":4096,"items":{"$ref":"#/$defs/Link"}},"errors":{"type":"array","maxItems":4096,"items":{"$ref":"#/$defs/ErrorHint"}},"statuses":{"$ref":"#/$defs/StatusCopy"},"design":{"$ref":"#/$defs/Design"},"raw":{"$ref":"#/$defs/RawEditor"},"response":{"$ref":"#/$defs/DisplaySpec"},"execution":{"$ref":"#/$defs/Execution"},"labels":{"$ref":"#/$defs/WorkbenchLabels"}},"required":["title","heading","purpose","audience","guidance","initial_operation","initial_example","operations","sections","links","errors","statuses","design","raw","response","execution","labels"]},"WorkbenchLabels":{"type":"object","additionalProperties":false,"properties":{"navigation":{"type":"string","maxLength":1048576},"operation":{"type":"string","maxLength":1048576},"examples":{"type":"string","maxLength":1048576},"load_example":{"type":"string","maxLength":1048576},"compute":{"type":"string","maxLength":1048576},"guide":{"type":"string","maxLength":1048576},"links":{"type":"string","maxLength":1048576},"fields":{"type":"string","maxLength":1048576},"expected_response":{"type":"string","maxLength":1048576},"details":{"type":"string","maxLength":1048576},"result_table":{"type":"string","maxLength":1048576},"row":{"type":"string","maxLength":1048576},"column":{"type":"string","maxLength":1048576},"request":{"type":"string","maxLength":1048576},"reset":{"type":"string","maxLength":1048576},"skip_to_workbench":{"type":"string","maxLength":1048576}},"required":["navigation","operation","examples","load_example","compute","guide","links","fields","expected_response","details","result_table","row","column","request","reset","skip_to_workbench"]}}}, "schemas/documents/model-provenance-v1.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://schemas.uor.foundation/prismpm/model-provenance/1","title":"ModelProvenance","description":"The payload of the https://uor.foundation/extension/prismpm-model/v1 extension, section row 3 (Foundation.Holo.V1.PrismExtension.ModelProvenance, ModelProvenanceV1 in crates/prismpm/src/holo/archive.rs).","type":"object","additionalProperties":false,"required":["application_kappa","cargo_crate_sha256","cargo_name","cargo_version","compiler_semantics_id","core_wasm_contract","generated_core_sha256","guest_content_kappa","hologram_live_commit","lcnf_manifest_sha256","lean4_prod_commit","lean_manifest_sha256","lexlean_commit","lexlean_package_sha256","model_content_kappa","model_id","prism_stdlib_crate_sha256","schema","semantic_id","snapshot_id","source_id","stdlib_semantics_id","target_profile_id","uor_hologram_commit","view_binding"],"properties":{"application_kappa":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"cargo_crate_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"cargo_name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"cargo_version":{"type":"string","minLength":1,"maxLength":128},"compiler_semantics_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"core_wasm_contract":{"const":"hologram:guest/core-wasm@1"},"generated_core_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"guest_content_kappa":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"hologram_live_commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"lcnf_manifest_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"lean4_prod_commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"lean_manifest_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"lexlean_commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"lexlean_package_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"model_content_kappa":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"model_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"prism_stdlib_crate_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"schema":{"const":"prismpm/model-provenance/1"},"semantic_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"snapshot_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"source_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"stdlib_semantics_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"target_profile_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"uor_hologram_commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"view_binding":{"description":"PrismPM requires the present form, with a present browser projection, for a portable view application.","oneOf":[{"type":"object","additionalProperties":false,"required":["tag"],"properties":{"tag":{"const":"none"}}},{"type":"object","additionalProperties":false,"required":["tag","browser_projection","view_content_kappa","view_model_id"],"properties":{"tag":{"const":"present"},"browser_projection":{"oneOf":[{"type":"object","additionalProperties":false,"required":["tag"],"properties":{"tag":{"const":"none"}}},{"type":"object","additionalProperties":false,"required":["tag","sha256"],"properties":{"tag":{"const":"present"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}]},"view_content_kappa":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"view_model_id":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}]}}}, + "schemas/documents/model-provenance-v2.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://schemas.uor.foundation/prismpm/model-provenance/2","title":"ModelProvenance","description":"Object 2 of a holo v5 (ADR-017): the model provenance, ModelProvenanceV1 in crates/prismpm/src/holo/archive.rs with every kappa a κ-label, sha256: and the hex SHA-256 of the bytes it names.","type":"object","additionalProperties":false,"required":["application_kappa","cargo_crate_sha256","cargo_name","cargo_version","compiler_semantics_id","core_wasm_contract","generated_core_sha256","guest_content_kappa","hologram_live_commit","lcnf_manifest_sha256","lean4_prod_commit","lean_manifest_sha256","lexlean_commit","lexlean_package_sha256","model_content_kappa","model_id","prism_stdlib_crate_sha256","schema","semantic_id","snapshot_id","source_id","stdlib_semantics_id","target_profile_id","uor_hologram_commit","view_binding"],"properties":{"application_kappa":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"cargo_crate_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"cargo_name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"cargo_version":{"type":"string","minLength":1,"maxLength":128},"compiler_semantics_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"core_wasm_contract":{"const":"hologram:guest/core-wasm@1"},"generated_core_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"guest_content_kappa":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"hologram_live_commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"lcnf_manifest_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"lean4_prod_commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"lean_manifest_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"lexlean_commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"lexlean_package_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"model_content_kappa":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"model_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"prism_stdlib_crate_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"schema":{"const":"prismpm/model-provenance/2"},"semantic_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"snapshot_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"source_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"stdlib_semantics_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"target_profile_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"uor_hologram_commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"view_binding":{"description":"PrismPM requires the present form, with a present browser projection, for a portable view application.","oneOf":[{"type":"object","additionalProperties":false,"required":["tag"],"properties":{"tag":{"const":"none"}}},{"type":"object","additionalProperties":false,"required":["tag","browser_projection","view_content_kappa","view_model_id"],"properties":{"tag":{"const":"present"},"browser_projection":{"oneOf":[{"type":"object","additionalProperties":false,"required":["tag"],"properties":{"tag":{"const":"none"}}},{"type":"object","additionalProperties":false,"required":["tag","sha256"],"properties":{"tag":{"const":"present"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}]},"view_content_kappa":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"view_model_id":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}]}}}, "schemas/holo/app-manifest.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://schemas.uor.foundation/prism/holo/app-manifest/1","title":"HoloAppManifest","description":"The decoded 356-byte application manifest, section kind 15 (Foundation.Holo.V1.Wire.validAppManifest).","type":"object","additionalProperties":false,"required":["uri","labels","suffix"],"properties":{"uri":{"const":"https://hologram.foundation/realization/app-manifest"},"labels":{"description":"The capability set, the Core-Wasm guest and the HOLOVIEW bundle, in that order.","type":"array","minItems":3,"maxItems":3,"prefixItems":[{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"}],"items":false},"suffix":{"description":"The fixed 86-byte layer suffix as lowercase hex (wireManifestSuffix).","const":"5200000000000000020000000008000000686f6c6f5f72756e1a000000686f6c6f6772616d3a67756573742f636f72652d7761736d4031030a000000696e6465782e68746d6c08000000706f727461626c6500000000"}}}, "schemas/holo/application-directory.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://schemas.uor.foundation/prism/holo/application-directory/1","title":"HoloApplicationDirectory","description":"The application-directory/v1 extension payload, section row 2, as PrismPM writes it (Directory in crates/prismpm/src/holo/archive.rs). Hologram owns the extension. Blobs are sorted by kappa.","type":"object","additionalProperties":false,"required":["schema_version","primary_layer","requires_kappa","layers","children","blobs"],"properties":{"schema_version":{"const":1},"primary_layer":{"const":0},"requires_kappa":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"layers":{"type":"array","minItems":2,"maxItems":2,"prefixItems":[{"type":"object","additionalProperties":false,"required":["position","kind","content_kappa","entry","contract","architecture","surface","engine"],"properties":{"position":{"const":0},"kind":{"const":"wasm"},"content_kappa":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"entry":{"const":"holo_run"},"contract":{"const":"hologram:guest/core-wasm@1"},"architecture":{"const":null},"surface":{"const":null},"engine":{"const":null}}},{"type":"object","additionalProperties":false,"required":["position","kind","content_kappa","entry","contract","architecture","surface","engine"],"properties":{"position":{"const":1},"kind":{"const":"view"},"content_kappa":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"entry":{"const":"index.html"},"contract":{"const":null},"architecture":{"const":null},"surface":{"const":"portable"},"engine":{"const":null}}}],"items":false},"children":{"type":"array","maxItems":0},"blobs":{"type":"array","minItems":4,"maxItems":4,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["kappa","byte_length"],"properties":{"kappa":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"byte_length":{"type":"integer","minimum":0,"maximum":9007199254740991}}}}}}, "schemas/holo/archive.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://schemas.uor.foundation/prism/holo/archive/1","title":"HoloArchive","description":"The decoded header, section table and footer of a holo, format revision 2026-10-23 (Foundation.Holo.V1.Wire). Sections are contiguous from offset 202 and end 32 bytes before the end of the file; JSON Schema cannot state that, so readers check it.","type":"object","additionalProperties":false,"required":["magic","version","flags","sections","footer"],"properties":{"magic":{"const":"HOLO"},"version":{"const":4},"flags":{"const":0},"sections":{"type":"array","minItems":8,"maxItems":8,"prefixItems":[{"type":"object","additionalProperties":false,"required":["kind","offset","length"],"properties":{"kind":{"const":15},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991,"const":202},"length":{"type":"integer","minimum":0,"maximum":9007199254740991,"const":356}}},{"type":"object","additionalProperties":false,"required":["kind","offset","length"],"properties":{"kind":{"const":8},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"length":{"type":"integer","minimum":0,"maximum":9007199254740991}}},{"type":"object","additionalProperties":false,"required":["kind","offset","length"],"properties":{"kind":{"const":14},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"length":{"type":"integer","minimum":0,"maximum":9007199254740991}}},{"type":"object","additionalProperties":false,"required":["kind","offset","length"],"properties":{"kind":{"const":14},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"length":{"type":"integer","minimum":0,"maximum":9007199254740991}}},{"type":"object","additionalProperties":false,"required":["kind","offset","length"],"properties":{"kind":{"const":16},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"length":{"type":"integer","minimum":71,"maximum":9007199254740991}}},{"type":"object","additionalProperties":false,"required":["kind","offset","length"],"properties":{"kind":{"const":16},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"length":{"type":"integer","minimum":71,"maximum":9007199254740991}}},{"type":"object","additionalProperties":false,"required":["kind","offset","length"],"properties":{"kind":{"const":16},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"length":{"type":"integer","minimum":71,"maximum":9007199254740991}}},{"type":"object","additionalProperties":false,"required":["kind","offset","length"],"properties":{"kind":{"const":16},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"length":{"type":"integer","minimum":71,"maximum":9007199254740991}}}],"items":false},"footer":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"The 32-byte BLAKE3 footer as lowercase hex: the archive fingerprint."}}}, @@ -1077,6 +1094,312 @@ const __reader = (() => { return Object.freeze({ readStructure }); })(); +// src/holo5.mjs +const __holo5 = (() => { + const { sha256Hex } = __sha256; + /** + * The checks of a holo v5 (ADR-017): a raw self-contained UORC archive + * (`"UORC" 02 01 00 00`, ULEB128 count and lengths, the objects, then the + * UORC-SHA256-CHAIN-v1 seal of every byte before it) whose ordered objects are + * the manifest, the source manifest, the provenance, the capability set, the + * guest, the view, the model and, when signed, the attestations. + * + * It records the checks of the v4 reader under the same ids, in the same + * shape, so a verdict on a v5 holo and on a v4 holo of the same application + * reach the same level for the same reasons. The Rust twin is + * crates/prismpm/src/inspect/verdict_v5.rs. Every identity is a κ-label, + * `sha256:` and the hex SHA-256 of the bytes it names. + */ + + const MANIFEST_SCHEMA = 'prism/holo/5'; + const PROVENANCE_SCHEMA = 'prismpm/model-provenance/2'; + const ROLES = Object.freeze(['manifest', 'source-manifest', 'provenance', 'capabilities', 'guest', 'view', 'model']); + const ROLE_ATTESTATIONS = 'attestations'; + const CONTENT = Object.freeze({ capabilities: 3, guest: 4, view: 5, model: 6 }); + const BUDGET = Object.freeze({ objects: 16, bytes: 2 ** 30 }); + const SEAL_LENGTH = 32; + const KAPPA = /^sha256:[0-9a-f]{64}$/; + const TAG = Uint8Array.from('UORC-SHA256-CHAIN-v1\0', (c) => c.charCodeAt(0)); + const utf8 = new TextDecoder('utf-8', { fatal: true }); + + /** Whether `bytes` start like a UORC archive. */ + const isUorc = (bytes) => bytes.length >= 4 && bytes[0] === 0x55 && bytes[1] === 0x4f && bytes[2] === 0x52 && bytes[3] === 0x43; + + const kappa = (bytes) => `sha256:${sha256Hex(bytes)}`; + + const fromHex = (hex) => Uint8Array.from(hex.match(/../g), (pair) => parseInt(pair, 16)); + function concat(parts) { + const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)); + let at = 0; + for (const part of parts) { + out.set(part, at); + at += part.length; + } + return out; + } + const sha = (parts) => fromHex(sha256Hex(concat(parts))); + + /** UORC-SHA256-CHAIN-v1 of `preimage`, as hex. */ + function chainHex(preimage) { + let c = sha([TAG, Uint8Array.of(0)]); + const whole = preimage.length - (preimage.length % 64); + for (let at = 0; at < whole; at += 64) c = sha([TAG, Uint8Array.of(1), c, preimage.subarray(at, at + 64)]); + const tail = preimage.subarray(whole); + return sha256Hex(concat([TAG, Uint8Array.of(2), c, Uint8Array.of(tail.length), tail])); + } + + function readUleb(bytes, at) { + let value = 0; + let scale = 1; + for (const start = at; ; ) { + if (at >= bytes.length || at - start > 7) return null; + const byte = bytes[at++]; + value += (byte & 0x7f) * scale; + scale *= 0x80; + if (byte < 0x80) return (byte === 0 && at - start > 1) || !Number.isSafeInteger(value) ? null : [value, at]; + } + } + + /** + * The framing of a raw self-contained UORC archive: `{ objects, seal, sealed }` + * with each object `{ index, offset, length, bytes }`, or `{ problem, check }` + * when its header cannot be read. The seal is reported, not enforced. + */ + function readArchive(bytes) { + const refuse = (problem, check = 'archive.table') => ({ problem, check }); + if (bytes.length < 6 || bytes[4] !== 2 || bytes[5] !== 1) return refuse('a holo v5 file is a UORC archive (format 2, profile 1)', 'archive.version'); + if (bytes.length < 8 + SEAL_LENGTH) return refuse('the UORC archive is truncated'); + const preimage = bytes.subarray(0, bytes.length - SEAL_LENGTH); + const seal = Array.from(bytes.subarray(bytes.length - SEAL_LENGTH), (b) => b.toString(16).padStart(2, '0')).join(''); + if (preimage[6] !== 0 || preimage[7] !== 0) return refuse('a holo is a self-contained archive whose objects are stored raw', 'archive.flags'); + let read = readUleb(preimage, 8); + if (!read) return refuse('the object count is not a ULEB128'); + const [count] = read; + if (count === 0 || count > BUDGET.objects) return refuse(`the archive declares ${count} objects; a holo holds 1 to ${BUDGET.objects}`); + let at = read[1]; + const lengths = []; + let total = 0; + for (let i = 0; i < count; i++) { + read = readUleb(preimage, at); + if (!read) return refuse('an object length is not a ULEB128'); + total += read[0]; + if (total > BUDGET.bytes) return refuse('the archive exceeds the decode budget'); + lengths.push(read[0]); + at = read[1]; + } + read = readUleb(preimage, at); + if (!read) return refuse('the body length is not a ULEB128'); + if (read[0] !== total || preimage.length - read[1] !== total) return refuse('the body length disagrees with the objects, or the archive has trailing bytes'); + let offset = read[1]; + const objects = lengths.map((length, index) => { + const object = { index, offset, length, bytes: preimage.subarray(offset, offset + length) }; + offset += length; + return object; + }); + return { objects, seal, sealed: chainHex(preimage) === seal }; + } + + /** JSON as the canonical form of a holo document: keys sorted, no whitespace. */ + function canonical(value) { + if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`; + if (value && typeof value === 'object') { + return `{${Object.keys(value) + .sort() + .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`) + .join(',')}}`; + } + return JSON.stringify(value); + } + + function decode(bytes) { + try { + const value = JSON.parse(utf8.decode(bytes)); + return value && typeof value === 'object' && !Array.isArray(value) ? { value } : { error: 'is not a JSON object' }; + } catch (error) { + return { error: `is not JSON: ${error.message}` }; + } + } + + /** + * The checks and facts of a holo v5, in the shape `analyze` returns for v4. + * + * @param {Uint8Array} bytes + * @param {{ spec: object, schemaErrors: Function, checkWorld: Function, order: string[], structureIds: string[], documentIds: string[], archiveIds: string[] }} context + */ + function analyzeV5(bytes, context) { + const { spec, schemaErrors, checkWorld } = context; + /** The two layers of a holo whose guest and view are named by these κ. */ + const layersOf = (guest, view) => [ + { contract: spec.CORE_WASM.CONTRACT, entry: spec.CORE_WASM.ENTRY, kappa: guest, kind: 'wasm' }, + { entry: spec.HOLOVIEW.ENTRY, kappa: view, kind: 'view', surface: 'portable' }, + ]; + const checks = [{ id: 'archive.magic', level: 'archive', status: 'pass', detail: 'magic UORC' }]; + const facts = { v5: true, structure: { ok: false }, sections: [], documents: {}, roles: {}, revision: null, layoutRevision: null, footer: null, fingerprint: null, newestDifferences: [] }; + const add = (level, id, ok, detail) => checks.push({ id, level, status: ok ? 'pass' : 'fail', detail }); + const skip = (level, id, detail) => checks.push({ id, level, status: 'skip', detail }); + + const archive = readArchive(bytes); + if (archive.problem) { + for (const id of context.structureIds.slice(1)) { + if (id === archive.check) add('archive', id, false, archive.problem); + else if (!checks.some((c) => c.id === archive.check)) add('archive', id, true, 'UORC format 2, profile 1'); + } + for (const id of context.archiveIds) if (!checks.some((c) => c.id === id)) skip('archive', id, `not checked: ${archive.check} failed`); + for (const id of context.documentIds) skip('documents', id, `not checked: ${archive.check} failed`); + return { checks, facts }; + } + add('archive', 'archive.version', true, 'UORC format 2, profile 1'); + add('archive', 'archive.flags', true, 'a self-contained archive, objects stored raw'); + add('archive', 'archive.table', true, `${archive.objects.length} objects, contiguous, ending at the seal`); + facts.structure.ok = true; + facts.footer = { stored: archive.seal, computed: archive.sealed ? archive.seal : null, matches: archive.sealed }; + facts.fingerprint = kappa(bytes); + add( + 'archive', + 'archive.footer', + archive.sealed, + archive.sealed ? `the seal is the UORC-SHA256-CHAIN-v1 of the archive, ${archive.seal}` : `the seal ${archive.seal} is not the UORC-SHA256-CHAIN-v1 of the archive: the archive was altered`, + ); + + const known = archive.objects.length === ROLES.length || archive.objects.length === ROLES.length + 1; + const contentRoles = new Map(Object.entries(CONTENT).map(([role, index]) => [index, role])); + facts.sections = archive.objects.map((object) => { + const role = ROLES[object.index] ?? ROLE_ATTESTATIONS; + const section = { index: object.index, kind: null, kindName: role, role, offset: object.offset, length: object.length, payload: object.bytes }; + if (contentRoles.has(object.index)) { + section.label = kappa(object.bytes); + section.content = object.bytes; + section.digests = { sha256: section.label.slice('sha256:'.length) }; + section.labelMatches = true; + } + return section; + }); + const at = (index) => (known ? facts.sections[index] : undefined); + const labelOf = (index) => at(index)?.label ?? (at(index) ? kappa(at(index).payload) : undefined); + + // manifest.wire and blob.labels: the manifest names every object by its κ. + { + const problems = []; + const decoded = at(0) ? decode(at(0).payload) : { error: 'is missing: the archive does not hold the objects of a holo' }; + const manifest = decoded.value; + if (decoded.error) problems.push(`the holo manifest ${decoded.error}`); + else { + if (manifest.schema !== MANIFEST_SCHEMA) problems.push(`the manifest names schema ${JSON.stringify(manifest.schema)}`); + if (typeof manifest.name !== 'string' || manifest.name.length === 0) problems.push('the manifest names no application'); + if (manifest.basis !== undefined && !KAPPA.test(manifest.basis)) problems.push('the manifest basis is not a κ-label'); + if (!KAPPA.test(manifest.requires)) problems.push('the manifest requires no κ-label'); + // The shape of the layers here; whether their κ name the objects is blob.labels. + const named = (i) => (Array.isArray(manifest.layers) ? manifest.layers[i]?.kappa : undefined); + if (canonical(manifest.layers) !== canonical(layersOf(named(0), named(1))) || ![named(0), named(1)].every((k) => KAPPA.test(k))) problems.push('the manifest layers are not the wasm and view layers of a holo'); + if (canonical(manifest) !== utf8.decode(at(0).payload)) problems.push('the manifest is not canonical JSON'); + } + if (problems.length === 0) facts.documents.manifest = manifest; + add('documents', 'manifest.wire', problems.length === 0, problems.length === 0 ? `the holo manifest is canonical ${MANIFEST_SCHEMA}` : problems.join('; ')); + if (manifest && problems.length === 0) { + // The provenance names the manifest, so the manifest lists every object but the provenance. + const expected = [1, 3, 4, 5, 6].map((i) => ({ kappa: labelOf(i), length: at(i).length, role: ROLES[i] })); + const ok = canonical(manifest.objects) === canonical(expected) && manifest.requires === labelOf(3) && canonical(manifest.layers) === canonical(layersOf(labelOf(4), labelOf(5))); + add('archive', 'blob.labels', ok, ok ? `all ${expected.length} objects match the κ the manifest gives them` : "the manifest's κ-labels and lengths are not those of the objects in their roles"); + } else skip('archive', 'blob.labels', 'not checked: manifest.wire failed'); + } + + const documentCheck = (id, what, object, schemaPath, key, check) => { + if (!object) return add('documents', id, false, `${what} is missing`); + const decoded = decode(object.payload ?? object.content); + if (decoded.error) return add('documents', id, false, `${what} ${decoded.error}`); + const path = typeof schemaPath === 'function' ? schemaPath(decoded.value) : schemaPath; + if (!path) return add('documents', id, false, `${what} names schema ${JSON.stringify(decoded.value?.schema)}, which no known format revision packs into a holo`); + const errors = schemaErrors(path, decoded.value) || (check ? check(decoded.value) : ''); + if (errors) return add('documents', id, false, `${what} does not match ${path}: ${errors}`); + facts.documents[key] = decoded.value; + return add('documents', id, true, `${what} matches ${path}`); + }; + const revisions = Object.values(spec.FORMAT_REVISIONS); + const modelSchemas = new Set(revisions.flatMap((r) => r.modelDocumentSchemas)); + + documentCheck('metadata.schema', 'the source manifest', at(1), spec.HOLO_SCHEMAS.SOURCE_MANIFEST, 'sourceManifest'); + skip('documents', 'directory.schema', 'not checked: a holo v5 names its layers in the manifest'); + documentCheck( + 'provenance.schema', + 'the model provenance', + at(2), + (v) => (v?.schema === PROVENANCE_SCHEMA ? spec.SCHEMAS[PROVENANCE_SCHEMA] : null), + 'provenance', + (v) => (canonical(v) === utf8.decode(at(2).payload) ? '' : 'it is not canonical JSON'), + ); + const provenance = facts.documents.provenance; + const modelBlob = at(CONTENT.model); + if (!provenance) skip('documents', 'model.schema', 'not checked: provenance.schema failed'); + else documentCheck('model.schema', 'the model document', modelBlob, (v) => (modelSchemas.has(v?.schema) ? spec.SCHEMAS[v.schema] : null), 'modelDocument'); + + if (known) for (const [role, index] of Object.entries(CONTENT)) facts.roles[role] = labelOf(index); + + // references: the provenance names the objects in their roles. + if (!provenance || !known) skip('documents', 'references', 'not checked: the provenance did not decode'); + else { + const problems = []; + for (const [role, recorded, actual] of [ + ['guest', provenance.guest_content_kappa, labelOf(4)], + ['model', provenance.model_content_kappa, labelOf(6)], + ['application', provenance.application_kappa, labelOf(0)], + ]) { + if (recorded !== actual) problems.push(`the provenance ${role} ${recorded} is not the ${role} object ${actual}`); + } + const binding = provenance.view_binding; + if (binding?.tag === 'present' && binding.view_content_kappa !== labelOf(5)) problems.push(`the provenance view ${binding.view_content_kappa} is not the view object ${labelOf(5)}`); + add('documents', 'references', problems.length === 0, problems.length === 0 ? 'the manifest and the provenance name the same objects' : problems.join('; ')); + } + + // model.sha256: as in v4. + if (!provenance || !modelBlob) skip('documents', 'model.sha256', 'not checked: no model document'); + else { + const actual = modelBlob.digests.sha256; + const problems = []; + if (provenance.model_id !== actual) problems.push(`the provenance model_id ${provenance.model_id} differs from the model document's sha256 ${actual}`); + const listed = facts.documents.sourceManifest?.files?.find((f) => f.kind === 'model-document'); + if (listed && listed.sha256 !== actual) problems.push(`the source manifest lists model-document sha256 ${listed.sha256}, the blob hashes to ${actual}`); + add('documents', 'model.sha256', problems.length === 0, problems.length === 0 ? `the model document's sha256 ${actual} equals the recorded model_id` : problems.join('; ')); + } + + // world.contract: as in v4, with the contract the provenance records. + const contract = provenance?.core_wasm_contract; + const guest = at(CONTENT.guest); + if (!contract || !guest) skip('documents', 'world.contract', 'not checked: the provenance or the guest is missing'); + else { + const world = checkWorld(contract, guest.content); + if (!world.known) skip('documents', 'world.contract', `not checked: this package has no world for the contract ${contract}`); + else add('documents', 'world.contract', world.conforms, world.conforms ? `the guest has exactly the imports and exports of the ${contract} world` : `the guest does not match the ${contract} world: ${world.problems.join('; ')}`); + } + + // format.revision: the roles, the contract, the source manifest and the view. + { + const revision = spec.FORMAT_REVISIONS[spec.FORMAT_REVISION]; + const differences = []; + if (!known) differences.push(`the archive holds ${archive.objects.length} objects, expected ${ROLES.length} or ${ROLES.length + 1} when signed`); + // As for v4: this package judges the unsigned holo, and `check` reads the attestations and strips them first. + if (archive.objects.length === ROLES.length + 1) differences.push(`the archive carries an ${ROLE_ATTESTATIONS} object, which this package does not read; check reads it`); + if (contract && contract !== revision.coreWasmContract) differences.push(`the guest contract is ${contract}, expected ${revision.coreWasmContract}`); + const sourceManifest = facts.documents.sourceManifest; + if (sourceManifest && sourceManifest.version !== revision.sourceManifestVersion) differences.push(`the source manifest version is ${sourceManifest.version}, expected ${revision.sourceManifestVersion}`); + const view = at(CONTENT.view)?.content; + if (view) { + const magic = view.length >= 10 ? String.fromCharCode(...view.subarray(0, 8)) : ''; + const version = view.length >= 10 ? (view[8] << 8) | view[9] : null; + if (magic !== spec.HOLOVIEW.MAGIC || version !== revision.holoviewVersion) differences.push(`the view is not a HOLOVIEW version ${revision.holoviewVersion} bundle`); + } + // A signed holo has no layout revision, so verdict refuses it as for v4; check strips the attestations first. + if (known && archive.objects.length === ROLES.length) facts.layoutRevision = spec.FORMAT_REVISION; + if (differences.length === 0) facts.revision = spec.FORMAT_REVISION; + facts.newestDifferences = differences; + add('documents', 'format.revision', differences.length === 0, differences.length === 0 ? `holo v5, format revision ${spec.FORMAT_REVISION}` : `the archive matches no format revision this package knows (holo v5): ${differences.join('; ')}`); + } + + checks.sort((a, b) => context.order.indexOf(a.id) - context.order.indexOf(b.id)); + return { checks, facts }; + } + return Object.freeze({ MANIFEST_SCHEMA, PROVENANCE_SCHEMA, ROLES, ROLE_ATTESTATIONS, isUorc, kappa, chainHex, readArchive, analyzeV5 }); +})(); + // src/asn1.mjs const __asn1 = (() => { /** @@ -2008,8 +2331,8 @@ const __vendor_predicates = (() => { // The predicate schemas the statement checks need, keyed by their path in @prism-code/spec, whitespace removed. const PREDICATE_SCHEMAS = Object.freeze({ - "predicates/proof-v1.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://uor.foundation/prism/proof/v1/schema.json","title":"ProofPredicateV1","description":"The predicate of an in-toto Statement v1 with predicateType https://uor.foundation/prism/proof/v1. The statement has exactly one subject, the Core-Wasm guest blob. The predicate names the verifier, the model, every theorem with its verdict, and the trusted computing base. Design: docs/proposals/266-proof-predicate.md. Digests are lowercase hex without an algorithm prefix.","type":"object","additionalProperties":false,"required":["verifier","policy","model","theorems","verificationResult","verifiedLevels","tcb","evidence","timeVerified"],"properties":{"verifier":{"description":"The kernel that produced the verdict, the compiler whose Lean output was checked, the producer of the statement and the image that hosted the check.","type":"object","additionalProperties":false,"required":["id","lean","lexlean","prismpm","sdkImage"],"properties":{"id":{"const":"https://uor.foundation/prism/verifier/lean4"},"lean":{"description":"tools.lock [lean] release and commit.","type":"object","additionalProperties":false,"required":["version","commit"],"properties":{"version":{"$ref":"#/$defs/Version"},"commit":{"$ref":"#/$defs/GitCommit"}}},"lexlean":{"description":"model/dependencies.toml lexlean, and model-provenance.json lexlean_commit and lexlean_package_sha256.","type":"object","additionalProperties":false,"required":["version","commit","crateSha256"],"properties":{"version":{"$ref":"#/$defs/Version"},"commit":{"$ref":"#/$defs/GitCommit"},"crateSha256":{"$ref":"#/$defs/HexDigest"}}},"prismpm":{"description":"prismpm.lock sdk_version.","type":"object","additionalProperties":false,"required":["version"],"properties":{"version":{"$ref":"#/$defs/Version"}}},"sdkImage":{"description":"prismpm.lock sdk_image: @sha256:.","type":"string","pattern":"^[^@\\s]+@sha256:[0-9a-f]{64}$"}}},"policy":{"description":"The per-declaration axiom policy table. Its digest is the LexLean snapshot that carries it.","type":"object","additionalProperties":false,"required":["uri","digest"],"properties":{"uri":{"type":"string","minLength":1,"format":"uri"},"digest":{"$ref":"#/$defs/Sha256Digest"}}},"model":{"description":"The model the theorems are about, as model-provenance.json and the model document's provenance state it.","type":"object","additionalProperties":false,"required":["document","sourceId","semanticId","snapshotId","compilerSemanticsId","leanManifestSha256","modules"],"properties":{"document":{"$ref":"#/$defs/PrismDigestSet"},"sourceId":{"$ref":"#/$defs/HexDigest"},"semanticId":{"$ref":"#/$defs/HexDigest"},"snapshotId":{"$ref":"#/$defs/HexDigest"},"compilerSemanticsId":{"$ref":"#/$defs/HexDigest"},"leanManifestSha256":{"$ref":"#/$defs/HexDigest"},"modules":{"description":"The Lean modules that were elaborated and replayed: the build manifest rows of kind lean.","type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["name","leanSha256"],"properties":{"name":{"$ref":"#/$defs/LeanName"},"leanSha256":{"$ref":"#/$defs/HexDigest"}}}}}},"theorems":{"description":"Every theorem of the model, with its verdict and axiom audit. Definitions, structures and inductives are not listed. A statement that lists no theorem claims nothing, so at least one is required.","type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["name","module","verdict","axioms"],"properties":{"name":{"description":"Full Lean name, namespace plus declaration, as written in the generated module.","$ref":"#/$defs/LeanName"},"module":{"$ref":"#/$defs/LeanName"},"verdict":{"$ref":"#/$defs/Verdict"},"axioms":{"description":"The observed axioms against the declared policy (VR-05).","type":"object","additionalProperties":false,"required":["policy","observed"],"properties":{"policy":{"type":"object","additionalProperties":false,"required":["kind","axioms"],"properties":{"kind":{"enum":["none","allow","exact"]},"axioms":{"$ref":"#/$defs/LeanNames"}}},"observed":{"$ref":"#/$defs/LeanNames"}}}}}},"verificationResult":{"description":"PASSED only when every theorem is PASSED and every leanchecker replay exited 0.","$ref":"#/$defs/Verdict"},"verifiedLevels":{"description":"The signer's claim, exactly one level as in SLSA. A proof statement supports at most P2, so the value is fixed (#269). A checker computes the level from evidence and never reads this claim.","const":["P2"]},"tcb":{"description":"The named trusted computing base: every component whose failure would make the verdict false. No entry is verified, and trust admits only trusted.","type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["component","role","version","trust"],"properties":{"component":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*$"},"role":{"type":"string","minLength":1},"version":{"$ref":"#/$defs/Version"},"digest":{"description":"Optional. A git commit or a SHA-256 digest, lowercase hex.","type":"string","pattern":"^([0-9a-f]{40}|[0-9a-f]{64})$"},"trust":{"const":"trusted"}}}},"evidence":{"description":"Digests a re-checker uses to fetch the retained evidence.","type":"object","additionalProperties":false,"required":["lexleanAttestation","verificationManifest"],"properties":{"lexleanAttestation":{"$ref":"#/$defs/Sha256Digest"},"verificationManifest":{"$ref":"#/$defs/Sha256Digest"}}},"timeVerified":{"description":"RFC 3339, UTC. Not an input to any identity.","type":"string","format":"date-time","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"}},"$defs":{"HexDigest":{"description":"64 lowercase hex characters.","type":"string","pattern":"^[0-9a-f]{64}$"},"GitCommit":{"description":"A git commit, 40 lowercase hex characters.","type":"string","pattern":"^[0-9a-f]{40}$"},"Version":{"type":"string","minLength":1,"maxLength":128},"LeanName":{"type":"string","minLength":1},"LeanNames":{"type":"array","uniqueItems":true,"items":{"$ref":"#/$defs/LeanName"}},"Verdict":{"enum":["PASSED","FAILED"]},"Sha256Digest":{"type":"object","additionalProperties":false,"required":["sha256"],"properties":{"sha256":{"$ref":"#/$defs/HexDigest"}}},"PrismDigestSet":{"description":"Exactly sha256 and blake3, lowercase hex, over the same bytes (ADR-015). blake3 is default-mode BLAKE3 with 256-bit output; for a content blob it equals the label without the blake3: prefix. The archive footer never appears here.","type":"object","additionalProperties":false,"required":["blake3","sha256"],"properties":{"blake3":{"type":"string","pattern":"^[0-9a-f]{64}$"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}}}, - "predicates/replay-v1.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://uor.foundation/prism/replay/v1/schema.json","title":"ReplayPredicateV1","description":"The predicate of an in-toto Statement v1 with predicateType https://uor.foundation/prism/replay/v1. The statement has exactly one subject, the Core-Wasm guest blob. The predicate names the runtime that re-executed the histories, the model of the build, every history by digest, and how many events diverged. It holds no clock, so the same replay writes the same bytes. Design: docs/proposals/284-histories-replay.md. Digests are lowercase hex without an algorithm prefix.","type":"object","additionalProperties":false,"required":["runtime","model","histories","divergenceCount"],"properties":{"runtime":{"description":"The runtime that re-executed the histories.","type":"object","additionalProperties":false,"required":["name","version"],"properties":{"name":{"description":"prism-code or prismpm.","type":"string","pattern":"^[a-z0-9][a-z0-9-]*$"},"version":{"type":"string","minLength":1,"maxLength":128}}},"model":{"description":"The model blob of the build that was replayed. sha256 is model_id; blake3 is the label of the blob without blake3:.","$ref":"#/$defs/PrismDigestSet"},"histories":{"description":"Every history that was replayed. A statement that replayed nothing claims nothing, so at least one is required.","type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["digest","events","divergences"],"properties":{"digest":{"description":"Both digests cover the canonical JSON of the history, with no trailing newline.","$ref":"#/$defs/PrismDigestSet"},"events":{"description":"Events re-executed. A history holds at least one.","type":"integer","minimum":1},"divergences":{"description":"Events whose outcome differs from the recording.","type":"integer","minimum":0}}}},"divergenceCount":{"description":"The sum of histories[].divergences. A check rejects a statement where they disagree, and anything but zero withholds P3.","type":"integer","minimum":0}},"$defs":{"PrismDigestSet":{"description":"Exactly sha256 and blake3, lowercase hex, over the same bytes (ADR-015). blake3 is default-mode BLAKE3 with 256-bit output.","type":"object","additionalProperties":false,"required":["blake3","sha256"],"properties":{"blake3":{"type":"string","pattern":"^[0-9a-f]{64}$"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}}}, + "predicates/proof-v1.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://uor.foundation/prism/proof/v1/schema.json","title":"ProofPredicateV1","description":"The predicate of an in-toto Statement v1 with predicateType https://uor.foundation/prism/proof/v1. The statement has exactly one subject, the Core-Wasm guest blob. The predicate names the verifier, the model, every theorem with its verdict, and the trusted computing base. Design: docs/proposals/266-proof-predicate.md. Digests are lowercase hex without an algorithm prefix.","type":"object","additionalProperties":false,"required":["verifier","policy","model","theorems","verificationResult","verifiedLevels","tcb","evidence","timeVerified"],"properties":{"verifier":{"description":"The kernel that produced the verdict, the compiler whose Lean output was checked, the producer of the statement and the image that hosted the check.","type":"object","additionalProperties":false,"required":["id","lean","lexlean","prismpm","sdkImage"],"properties":{"id":{"const":"https://uor.foundation/prism/verifier/lean4"},"lean":{"description":"tools.lock [lean] release and commit.","type":"object","additionalProperties":false,"required":["version","commit"],"properties":{"version":{"$ref":"#/$defs/Version"},"commit":{"$ref":"#/$defs/GitCommit"}}},"lexlean":{"description":"model/dependencies.toml lexlean, and model-provenance.json lexlean_commit and lexlean_package_sha256.","type":"object","additionalProperties":false,"required":["version","commit","crateSha256"],"properties":{"version":{"$ref":"#/$defs/Version"},"commit":{"$ref":"#/$defs/GitCommit"},"crateSha256":{"$ref":"#/$defs/HexDigest"}}},"prismpm":{"description":"prismpm.lock sdk_version.","type":"object","additionalProperties":false,"required":["version"],"properties":{"version":{"$ref":"#/$defs/Version"}}},"sdkImage":{"description":"prismpm.lock sdk_image: @sha256:.","type":"string","pattern":"^[^@\\s]+@sha256:[0-9a-f]{64}$"}}},"policy":{"description":"The per-declaration axiom policy table. Its digest is the LexLean snapshot that carries it.","type":"object","additionalProperties":false,"required":["uri","digest"],"properties":{"uri":{"type":"string","minLength":1,"format":"uri"},"digest":{"$ref":"#/$defs/Sha256Digest"}}},"model":{"description":"The model the theorems are about, as model-provenance.json and the model document's provenance state it.","type":"object","additionalProperties":false,"required":["document","sourceId","semanticId","snapshotId","compilerSemanticsId","leanManifestSha256","modules"],"properties":{"document":{"$ref":"#/$defs/PrismDigestSet"},"sourceId":{"$ref":"#/$defs/HexDigest"},"semanticId":{"$ref":"#/$defs/HexDigest"},"snapshotId":{"$ref":"#/$defs/HexDigest"},"compilerSemanticsId":{"$ref":"#/$defs/HexDigest"},"leanManifestSha256":{"$ref":"#/$defs/HexDigest"},"modules":{"description":"The Lean modules that were elaborated and replayed: the build manifest rows of kind lean.","type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["name","leanSha256"],"properties":{"name":{"$ref":"#/$defs/LeanName"},"leanSha256":{"$ref":"#/$defs/HexDigest"}}}}}},"theorems":{"description":"Every theorem of the model, with its verdict and axiom audit. Definitions, structures and inductives are not listed. A statement that lists no theorem claims nothing, so at least one is required.","type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["name","module","verdict","axioms"],"properties":{"name":{"description":"Full Lean name, namespace plus declaration, as written in the generated module.","$ref":"#/$defs/LeanName"},"module":{"$ref":"#/$defs/LeanName"},"verdict":{"$ref":"#/$defs/Verdict"},"axioms":{"description":"The observed axioms against the declared policy (VR-05).","type":"object","additionalProperties":false,"required":["policy","observed"],"properties":{"policy":{"type":"object","additionalProperties":false,"required":["kind","axioms"],"properties":{"kind":{"enum":["none","allow","exact"]},"axioms":{"$ref":"#/$defs/LeanNames"}}},"observed":{"$ref":"#/$defs/LeanNames"}}}}}},"verificationResult":{"description":"PASSED only when every theorem is PASSED and every leanchecker replay exited 0.","$ref":"#/$defs/Verdict"},"verifiedLevels":{"description":"The signer's claim, exactly one level as in SLSA. A proof statement supports at most P2, so the value is fixed (#269). A checker computes the level from evidence and never reads this claim.","const":["P2"]},"tcb":{"description":"The named trusted computing base: every component whose failure would make the verdict false. No entry is verified, and trust admits only trusted.","type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["component","role","version","trust"],"properties":{"component":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*$"},"role":{"type":"string","minLength":1},"version":{"$ref":"#/$defs/Version"},"digest":{"description":"Optional. A git commit or a SHA-256 digest, lowercase hex.","type":"string","pattern":"^([0-9a-f]{40}|[0-9a-f]{64})$"},"trust":{"const":"trusted"}}}},"evidence":{"description":"Digests a re-checker uses to fetch the retained evidence.","type":"object","additionalProperties":false,"required":["lexleanAttestation","verificationManifest"],"properties":{"lexleanAttestation":{"$ref":"#/$defs/Sha256Digest"},"verificationManifest":{"$ref":"#/$defs/Sha256Digest"}}},"timeVerified":{"description":"RFC 3339, UTC. Not an input to any identity.","type":"string","format":"date-time","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"}},"$defs":{"HexDigest":{"description":"64 lowercase hex characters.","type":"string","pattern":"^[0-9a-f]{64}$"},"GitCommit":{"description":"A git commit, 40 lowercase hex characters.","type":"string","pattern":"^[0-9a-f]{40}$"},"Version":{"type":"string","minLength":1,"maxLength":128},"LeanName":{"type":"string","minLength":1},"LeanNames":{"type":"array","uniqueItems":true,"items":{"$ref":"#/$defs/LeanName"}},"Verdict":{"enum":["PASSED","FAILED"]},"Sha256Digest":{"type":"object","additionalProperties":false,"required":["sha256"],"properties":{"sha256":{"$ref":"#/$defs/HexDigest"}}},"PrismDigestSet":{"description":"sha256, the κ of the bytes (ADR-017); blake3 beside it only in statements and documents about a v4 holo (ADR-015). Lowercase hex.","type":"object","additionalProperties":false,"required":["sha256"],"properties":{"blake3":{"type":"string","pattern":"^[0-9a-f]{64}$"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}}}, + "predicates/replay-v1.schema.json": {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://uor.foundation/prism/replay/v1/schema.json","title":"ReplayPredicateV1","description":"The predicate of an in-toto Statement v1 with predicateType https://uor.foundation/prism/replay/v1. The statement has exactly one subject, the Core-Wasm guest blob. The predicate names the runtime that re-executed the histories, the model of the build, every history by digest, and how many events diverged. It holds no clock, so the same replay writes the same bytes. Design: docs/proposals/284-histories-replay.md. Digests are lowercase hex without an algorithm prefix.","type":"object","additionalProperties":false,"required":["runtime","model","histories","divergenceCount"],"properties":{"runtime":{"description":"The runtime that re-executed the histories.","type":"object","additionalProperties":false,"required":["name","version"],"properties":{"name":{"description":"prism-code or prismpm.","type":"string","pattern":"^[a-z0-9][a-z0-9-]*$"},"version":{"type":"string","minLength":1,"maxLength":128}}},"model":{"description":"The model blob of the build that was replayed. sha256 is model_id; blake3 is the label of the blob without blake3:.","$ref":"#/$defs/PrismDigestSet"},"histories":{"description":"Every history that was replayed. A statement that replayed nothing claims nothing, so at least one is required.","type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["digest","events","divergences"],"properties":{"digest":{"description":"Both digests cover the canonical JSON of the history, with no trailing newline.","$ref":"#/$defs/PrismDigestSet"},"events":{"description":"Events re-executed. A history holds at least one.","type":"integer","minimum":1},"divergences":{"description":"Events whose outcome differs from the recording.","type":"integer","minimum":0}}}},"divergenceCount":{"description":"The sum of histories[].divergences. A check rejects a statement where they disagree, and anything but zero withholds P3.","type":"integer","minimum":0}},"$defs":{"PrismDigestSet":{"description":"sha256, the κ of the bytes (ADR-017); blake3 beside it only in statements and documents about a v4 holo (ADR-015). Lowercase hex.","type":"object","additionalProperties":false,"required":["sha256"],"properties":{"blake3":{"type":"string","pattern":"^[0-9a-f]{64}$"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}}}, }); return Object.freeze({ PREDICATE_SCHEMAS }); })(); @@ -2034,6 +2357,17 @@ const __statements = (() => { const { ASSURANCE } = assurance; + /** + * Whether the digest set a statement gives names `actual`, the digests of an object of this holo: its sha256, the κ + * (ADR-017), is equal, and a blake3 beside it, which only statements about a v4 holo carry (ADR-015), is equal too. + */ + const sameDigests = (digest, actual) => + isObject(digest) && + Boolean(actual) && + Object.keys(digest).every((key) => key === 'sha256' || key === 'blake3') && + digest.sha256 === actual.sha256 && + (digest.blake3 === undefined || digest.blake3 === actual.blake3); + const STATEMENT_TYPE = 'https://in-toto.io/Statement/v1'; const PROOF_PREDICATE_TYPE = ASSURANCE.PREDICATES.proof; const PROOF_SCHEMA = 'predicates/proof-v1.schema.json'; @@ -2096,13 +2430,13 @@ const __statements = (() => { const { subject, predicate } = statement; const digest = subject[0].digest; - if (!holo.guest || digest.blake3 !== holo.guest.blake3 || digest.sha256 !== holo.guest.sha256) { - reasons.push(reason('proof.subject', `The proof statement is about ${subject[0].name} with blake3 ${digest.blake3}, which is not this holo's guest${holo.guest ? ` (blake3 ${holo.guest.blake3})` : ''}.`)); + if (!sameDigests(digest, holo.guest)) { + reasons.push(reason('proof.subject', `The proof statement is about ${subject[0].name} with sha256 ${digest.sha256}, which is not this holo's guest${holo.guest ? ` (sha256 ${holo.guest.sha256})` : ''}.`)); } const model = []; const document = predicate.model.document; - if (!holo.model || document.sha256 !== holo.model.sha256 || document.blake3 !== holo.model.blake3) model.push('the model document digests are not those of the model blob'); + if (!sameDigests(document, holo.model)) model.push('the model document digests are not those of the model blob'); const provenance = holo.provenance ?? {}; const pairs = [ ['document.sha256', document.sha256, 'model_id'], @@ -2168,7 +2502,7 @@ const __statements = (() => { } const unmatched = subjects.filter((subject) => { const digest = subject?.digest; - return !isObject(digest) || !holo.blobs.some((blob) => blob.digests && blob.digests.sha256 === digest.sha256 && blob.digests.blake3 === digest.blake3); + return !holo.blobs.some((blob) => sameDigests(digest, blob.digests)); }); if (unmatched.length > 0) { reasons.push(withheld('provenance.subject', `The provenance statement names ${unmatched.map((s) => s?.name ?? '(unnamed)').join(', ')}, which this holo does not contain with those digests.`)); @@ -2192,7 +2526,6 @@ const __statements = (() => { return { check, code: REPLAY_CODES[check], withholds: 'P3', message }; } - const sameDigests = (a, b) => Boolean(a && b) && a.sha256 === b.sha256 && a.blake3 === b.blake3; /** * Check one replay statement against a build. Returns the reasons, in check @@ -2229,17 +2562,17 @@ const __statements = (() => { const { subject, predicate } = statement; if (!sameDigests(subject[0].digest, holo.guest)) { - reasons.push(replayReason('replay.subject', `The replay statement is about ${subject[0].name} with blake3 ${subject[0].digest.blake3}, which is not this holo's guest${holo.guest ? ` (blake3 ${holo.guest.blake3})` : ''}.`)); + reasons.push(replayReason('replay.subject', `The replay statement is about ${subject[0].name} with sha256 ${subject[0].digest.sha256}, which is not this holo's guest${holo.guest ? ` (sha256 ${holo.guest.sha256})` : ''}.`)); } if (!sameDigests(predicate.model, holo.model)) { - reasons.push(replayReason('replay.model', `The replay statement is about the model with blake3 ${predicate.model.blake3}, which is not this holo's model${holo.model ? ` (blake3 ${holo.model.blake3})` : ''}.`)); + reasons.push(replayReason('replay.model', `The replay statement is about the model with sha256 ${predicate.model.sha256}, which is not this holo's model${holo.model ? ` (sha256 ${holo.model.sha256})` : ''}.`)); } if (predicate.divergenceCount > 0) { reasons.push(replayReason('replay.divergence', `The replay recorded ${predicate.divergenceCount} divergences from its histories.`)); } return reasons; } - return Object.freeze({ STATEMENT_TYPE, PROOF_PREDICATE_TYPE, PROOF_SCHEMA, TCB_COMPONENTS, PROOF_CODES, checkProofStatement, PROVENANCE_PREDICATE_TYPE, checkProvenanceStatement, REPLAY_PREDICATE_TYPE, REPLAY_SCHEMA, REPLAY_CODES, checkReplayStatement }); + return Object.freeze({ sameDigests, STATEMENT_TYPE, PROOF_PREDICATE_TYPE, PROOF_SCHEMA, TCB_COMPONENTS, PROOF_CODES, checkProofStatement, PROVENANCE_PREDICATE_TYPE, checkProvenanceStatement, REPLAY_PREDICATE_TYPE, REPLAY_SCHEMA, REPLAY_CODES, checkReplayStatement }); })(); // src/world.mjs @@ -3643,7 +3976,7 @@ const __vendor_policies = (() => { "provenance-only": "# Provenance only: the holo carries a provenance statement whose signature checks, and no proof is\n# required. P1 includes the integrity of the archive, so a damaged holo cannot reach it.\npackage prism.policy\n\nimport rego.v1\n\nminimum := \"P1\"\n\ndeny contains {\"rule\": \"policy.provenance-only.absent\", \"message\": \"the holo carries no provenance statement\"} if {\n\tinput.predicates.provenance == null\n}\n\ndeny contains {\"rule\": \"policy.provenance-only.unverified\", \"message\": \"the provenance statement signature does not check against the trust root\"} if {\n\tinput.predicates.provenance.verified == false\n}\n", }); - const POLICY_INPUT_JSON_SCHEMA = {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://schemas.uor.foundation/prism/policy-input/1","title":"PolicyInput","description":"The document a policy judges, bound to `input` when a policy file is evaluated. It holds what the check found: the evidence, the declared world, the granted capabilities and the attested predicates. It never holds a policy, and nothing in it is read from a policy section of the holo. Design: docs/proposals/285-policy-file.md.","type":"object","additionalProperties":false,"required":["schema","holo","verdict","world","capabilities","predicates"],"properties":{"schema":{"const":"prism/policy-input/1"},"holo":{"type":"object","additionalProperties":false,"required":["fingerprint","revision","digests"],"properties":{"fingerprint":{"description":"The archive fingerprint, the same value as the holo member of a verdict.","type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"revision":{"description":"The format revision the archive matches, or null when it matches none.","type":["string","null"]},"digests":{"description":"Both digests of the whole file and of each content blob that could be located.","type":"object","additionalProperties":false,"required":["archive"],"properties":{"archive":{"$ref":"#/$defs/digests"},"capabilities":{"$ref":"#/$defs/digests"},"guest":{"$ref":"#/$defs/digests"},"view":{"$ref":"#/$defs/digests"},"model":{"$ref":"#/$defs/digests"}}}}},"verdict":{"description":"The evidence: the assurance level and every check that did not pass, before any policy judged them. A policy never changes the level.","type":"object","additionalProperties":false,"required":["level","reasons"],"properties":{"level":{"$ref":"#/$defs/level"},"reasons":{"type":"array","maxItems":1024,"items":{"$ref":"#/$defs/reason"}}}},"world":{"description":"The world the holo declares, or null when it names no guest contract.","oneOf":[{"type":"null"},{"$ref":"#/$defs/world"}]},"capabilities":{"description":"The capability set the caller granted, or null when nothing was granted. A policy file never grants; only the caller does.","oneOf":[{"type":"null"},{"$ref":"#/$defs/capabilitySet"}]},"predicates":{"description":"The attested statements the holo carries, by the kind of evidence each is. Null when the holo carries none of that kind.","type":"object","additionalProperties":false,"required":["provenance","proof","replay"],"properties":{"provenance":{"$ref":"#/$defs/predicate"},"proof":{"$ref":"#/$defs/predicate"},"replay":{"$ref":"#/$defs/predicate"}}}},"$defs":{"level":{"description":"P0 unverified, P1 provenance, P2 proof checked, P3 proof, replay and world.","enum":["P0","P1","P2","P3"]},"digests":{"type":"object","additionalProperties":false,"required":["sha256","blake3"],"properties":{"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"blake3":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},"reason":{"description":"One check that did not pass, the same shape as a reason of prism/verdict/1.","type":"object","additionalProperties":false,"required":["check","withholds","message"],"properties":{"check":{"type":"string","pattern":"^[a-z][a-z0-9-]*([.][a-z][a-z0-9-]*)+$"},"code":{"type":"string","pattern":"^PP[0-9]{4}$"},"withholds":{"enum":["P1","P2","P3",null]},"message":{"type":"string","minLength":1,"maxLength":1024}}},"world":{"type":"object","additionalProperties":false,"required":["contract","known","within","pure","effects","imports","problems","capability_set"],"properties":{"contract":{"type":"string","minLength":1},"known":{"description":"False when this reader has no world for the contract. Then within, pure, effects and imports are null and nothing is stated about them.","type":"boolean"},"within":{"type":["boolean","null"]},"pure":{"type":["boolean","null"]},"effects":{"oneOf":[{"type":"null"},{"type":"array","items":{"enum":["clock","random","socket","filesystem","unknown"]}}]},"imports":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"object","additionalProperties":false,"required":["module","name","kind"],"properties":{"module":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"capability":{"enum":["outbound-hosts","key-value-stores","variables"]}}}}]},"problems":{"type":"array","items":{"type":"string"}},"capability_set":{"description":"The capability set blob the holo itself carries, or null when it could not be located. Empty means the holo requests nothing.","oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["label","empty"],"properties":{"label":{"type":"string","pattern":"^blake3:[0-9a-f]{64}$"},"empty":{"type":"boolean"}}}]}}},"capabilitySet":{"type":"object","additionalProperties":false,"properties":{"allow-outbound-hosts":{"$ref":"#/$defs/entries"},"deny-outbound-hosts":{"$ref":"#/$defs/entries"},"allow-key-value-stores":{"$ref":"#/$defs/entries"},"deny-key-value-stores":{"$ref":"#/$defs/entries"},"allow-variables":{"$ref":"#/$defs/entries"},"deny-variables":{"$ref":"#/$defs/entries"},"allow-providers":{"$ref":"#/$defs/entries"},"deny-providers":{"$ref":"#/$defs/entries"}}},"entries":{"type":"array","items":{"type":"string"}},"predicate":{"description":"One attested statement, or null. verified says its signature checked against the trust root.","oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["predicateType","verified","predicate"],"properties":{"predicateType":{"type":"string","minLength":1},"verified":{"type":"boolean"},"predicate":{"type":"object"}}}]}}}; + const POLICY_INPUT_JSON_SCHEMA = {"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://schemas.uor.foundation/prism/policy-input/1","title":"PolicyInput","description":"The document a policy judges, bound to `input` when a policy file is evaluated. It holds what the check found: the evidence, the declared world, the granted capabilities and the attested predicates. It never holds a policy, and nothing in it is read from a policy section of the holo. Design: docs/proposals/285-policy-file.md.","type":"object","additionalProperties":false,"required":["schema","holo","verdict","world","capabilities","predicates"],"properties":{"schema":{"const":"prism/policy-input/1"},"holo":{"type":"object","additionalProperties":false,"required":["fingerprint","revision","digests"],"properties":{"fingerprint":{"description":"The archive fingerprint, the same value as the holo member of a verdict.","type":"string","pattern":"^(sha256|blake3):[0-9a-f]{64}$"},"revision":{"description":"The format revision the archive matches, or null when it matches none.","type":["string","null"]},"digests":{"description":"Both digests of the whole file and of each content blob that could be located.","type":"object","additionalProperties":false,"required":["archive"],"properties":{"archive":{"$ref":"#/$defs/digests"},"capabilities":{"$ref":"#/$defs/digests"},"guest":{"$ref":"#/$defs/digests"},"view":{"$ref":"#/$defs/digests"},"model":{"$ref":"#/$defs/digests"}}}}},"verdict":{"description":"The evidence: the assurance level and every check that did not pass, before any policy judged them. A policy never changes the level.","type":"object","additionalProperties":false,"required":["level","reasons"],"properties":{"level":{"$ref":"#/$defs/level"},"reasons":{"type":"array","maxItems":1024,"items":{"$ref":"#/$defs/reason"}}}},"world":{"description":"The world the holo declares, or null when it names no guest contract.","oneOf":[{"type":"null"},{"$ref":"#/$defs/world"}]},"capabilities":{"description":"The capability set the caller granted, or null when nothing was granted. A policy file never grants; only the caller does.","oneOf":[{"type":"null"},{"$ref":"#/$defs/capabilitySet"}]},"predicates":{"description":"The attested statements the holo carries, by the kind of evidence each is. Null when the holo carries none of that kind.","type":"object","additionalProperties":false,"required":["provenance","proof","replay"],"properties":{"provenance":{"$ref":"#/$defs/predicate"},"proof":{"$ref":"#/$defs/predicate"},"replay":{"$ref":"#/$defs/predicate"}}}},"$defs":{"level":{"description":"P0 unverified, P1 provenance, P2 proof checked, P3 proof, replay and world.","enum":["P0","P1","P2","P3"]},"digests":{"type":"object","additionalProperties":false,"required":["sha256"],"properties":{"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"blake3":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},"reason":{"description":"One check that did not pass, the same shape as a reason of prism/verdict/1.","type":"object","additionalProperties":false,"required":["check","withholds","message"],"properties":{"check":{"type":"string","pattern":"^[a-z][a-z0-9-]*([.][a-z][a-z0-9-]*)+$"},"code":{"type":"string","pattern":"^PP[0-9]{4}$"},"withholds":{"enum":["P1","P2","P3",null]},"message":{"type":"string","minLength":1,"maxLength":1024}}},"world":{"type":"object","additionalProperties":false,"required":["contract","known","within","pure","effects","imports","problems","capability_set"],"properties":{"contract":{"type":"string","minLength":1},"known":{"description":"False when this reader has no world for the contract. Then within, pure, effects and imports are null and nothing is stated about them.","type":"boolean"},"within":{"type":["boolean","null"]},"pure":{"type":["boolean","null"]},"effects":{"oneOf":[{"type":"null"},{"type":"array","items":{"enum":["clock","random","socket","filesystem","unknown"]}}]},"imports":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"object","additionalProperties":false,"required":["module","name","kind"],"properties":{"module":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"capability":{"enum":["outbound-hosts","key-value-stores","variables"]}}}}]},"problems":{"type":"array","items":{"type":"string"}},"capability_set":{"description":"The capability set blob the holo itself carries, or null when it could not be located. Empty means the holo requests nothing.","oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["label","empty"],"properties":{"label":{"type":"string","pattern":"^(sha256|blake3):[0-9a-f]{64}$"},"empty":{"type":"boolean"}}}]}}},"capabilitySet":{"type":"object","additionalProperties":false,"properties":{"allow-outbound-hosts":{"$ref":"#/$defs/entries"},"deny-outbound-hosts":{"$ref":"#/$defs/entries"},"allow-key-value-stores":{"$ref":"#/$defs/entries"},"deny-key-value-stores":{"$ref":"#/$defs/entries"},"allow-variables":{"$ref":"#/$defs/entries"},"deny-variables":{"$ref":"#/$defs/entries"},"allow-providers":{"$ref":"#/$defs/entries"},"deny-providers":{"$ref":"#/$defs/entries"}}},"entries":{"type":"array","items":{"type":"string"}},"predicate":{"description":"One attested statement, or null. verified says its signature checked against the trust root.","oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["predicateType","verified","predicate"],"properties":{"predicateType":{"type":"string","minLength":1},"verified":{"type":"boolean"},"predicate":{"type":"object"}}}]}}}; return Object.freeze({ POLICY_SOURCES, POLICY_INPUT_JSON_SCHEMA }); })(); @@ -3743,6 +4076,7 @@ const __index = (() => { const { SCHEMA_FILES } = __vendor_schemas; const { sha256Hex } = __sha256; const { readStructure } = __reader; + const { analyzeV5, isUorc } = __holo5; const assurance = __vendor_assurance_levels; const transparency = __transparency; const { levelOf } = __level; @@ -3841,6 +4175,9 @@ const __index = (() => { return { sha256: sha256Hex(bytes), blake3: blake3Hex(bytes) }; } + /** The digest set of the whole file: its κ alone for a holo v5 (ADR-017), both digests for v4. */ + const archiveDigests = (bytes, facts) => (facts.v5 ? { sha256: sha256Hex(bytes) } : digestsOf(bytes)); + function isLabel(bytes) { if (bytes.length !== spec.LABEL_LENGTH) return false; for (let i = 0; i < spec.LABEL_PREFIX.length; i++) if (bytes[i] !== spec.LABEL_PREFIX.charCodeAt(i)) return false; @@ -3906,6 +4243,9 @@ const __index = (() => { /** Every check, and the facts both entry points report, computed once. */ function analyze(bytes) { + if (isUorc(bytes)) { + return analyzeV5(bytes, { spec, schemaErrors, checkWorld, order: [...ARCHIVE_IDS, ...DOCUMENT_IDS], structureIds: STRUCTURE_IDS, archiveIds: ARCHIVE_IDS, documentIds: DOCUMENT_IDS }); + } const structure = readStructure(bytes); const checks = structure.checks.map((c) => ({ ...c, level: 'archive' })); const facts = { structure, sections: [], documents: {}, roles: {}, revision: null, layoutRevision: null, footer: null, fingerprint: null }; @@ -4350,6 +4690,87 @@ const __index = (() => { }; } + /** + * The `prismpm/holo-inspection/1` object of a holo v5 (ADR-017): the same members as for v4, where every section is one + * object of the UORC archive, kind and role are the object's role, every digest is the object's κ alone, the footer is + * the UORC-SHA256-CHAIN-v1 seal and the manifest labels are the κ the holo manifest names. + */ + function inspectionOfV5(bytes, facts, checks) { + const status = (id) => checks.find((c) => c.id === id)?.status === 'pass'; + const kappaOf = (payload) => ({ sha256: sha256Hex(payload) }); + const objectOf = (role) => facts.sections.find((s) => s.role === role); + const sections = facts.sections.map((s) => ({ + index: s.index, + kind: null, + kind_name: s.role, + role: s.role, + offset: s.offset, + length: s.length, + digest: kappaOf(s.payload), + label: `sha256:${sha256Hex(s.payload)}`, + })); + const { manifest, provenance, modelDocument } = facts.documents; + const application = modelDocument?.application ?? {}; + const labelOf = (role) => orNull(objectOf(role) && `sha256:${sha256Hex(objectOf(role).payload)}`); + const capabilities = objectOf('capabilities'); + const guest = objectOf('guest'); + const model = objectOf('model'); + const wasm = manifest?.layers?.find((l) => l.kind === 'wasm'); + const contract = wasm?.contract ?? null; + return { + schema: INSPECTION_SCHEMA, + name: application.name ?? manifest?.name ?? null, + revision: facts.revision, + physical_version: 5, + flags: 0, + size: bytes.length, + digest: kappaOf(bytes), + footer: facts.footer.stored, + sections, + manifest: manifest + ? { uri: manifest.schema, labels: { capability_set: labelOf('capabilities'), guest: labelOf('guest'), view: labelOf('view') }, ...MANIFEST_SUFFIX_FIELDS } + : null, + model: + modelDocument && model + ? { + schema: orNull(modelDocument.schema), + name: orNull(application.name), + cargo_name: orNull(application.cargo_name), + cargo_version: orNull(application.cargo_version), + description: orNull(application.cargo_description), + profile: orNull(application.profile), + function: orNull(application.function_name), + vectors: Array.isArray(application.acceptance_vectors) ? application.acceptance_vectors.length : 0, + limits: { + request: orNull(application.request_maximum), + response: orNull(application.response_maximum), + guest_allocation: orNull(application.guest_allocation_maximum), + }, + digest: kappaOf(model.payload), + } + : null, + provenance: provenance + ? { + schema: orNull(provenance.schema), + application_kappa: orNull(provenance.application_kappa), + model_id: orNull(provenance.model_id), + compiler_semantics_id: orNull(provenance.compiler_semantics_id), + stdlib_semantics_id: orNull(provenance.stdlib_semantics_id), + lexlean_commit: orNull(provenance.lexlean_commit), + } + : null, + world: + contract && capabilities + ? { + ...describeWorld(contract, guest ? guest.payload : null), + capability_set: { label: labelOf('capabilities'), empty: hex(capabilities.payload) === spec.CAPABILITY_SET.EMPTY_HEX }, + } + : null, + attestations: [], + verification: { footer: status('archive.footer'), labels: status('blob.labels'), cross_references: status('references') }, + }; + } + /** * Describe a holo as a `prismpm/holo-inspection/1` object. Throws VerifyError * when the header or section table cannot be read, because then there are no @@ -4364,7 +4785,7 @@ const __index = (() => { const { checks, facts } = analyze(bytes); const broken = checks.find((c) => c.status === 'fail' && STRUCTURE_IDS.includes(c.id)); if (broken) throw new VerifyError(broken.id, broken.detail); - return inspectionOf(bytes, facts, checks); + return facts.v5 ? inspectionOfV5(bytes, facts, checks) : inspectionOf(bytes, facts, checks); } /** @@ -4570,7 +4991,7 @@ const __index = (() => { function inputOf(bytes, evidence, capabilities) { const { facts, reasons, contract, world, replay, attested, level } = evidence; const blob = (role) => (facts.roles[role] ? facts.sections.find((s) => s.label === facts.roles[role]) : undefined); - const digests = { archive: digestsOf(bytes) }; + const digests = { archive: archiveDigests(bytes, facts) }; for (const role of ['capabilities', 'guest', 'view', 'model']) { const section = blob(role); if (section?.digests) digests[role] = section.digests; @@ -4660,7 +5081,7 @@ const __index = (() => { } for (const [target, expected] of Object.entries(wanted.digests)) { let actual = null; - if (target === 'archive') actual = digestsOf(bytes); + if (target === 'archive') actual = archiveDigests(bytes, facts); else if (facts.roles[target]) actual = facts.sections.find((s) => s.label === facts.roles[target])?.digests ?? null; const mismatches = actual ? Object.entries(expected) diff --git a/studio/shell/prism-code/src/version.mjs b/studio/shell/prism-code/src/version.mjs index 90c52739..fb1dc85c 100644 --- a/studio/shell/prism-code/src/version.mjs +++ b/studio/shell/prism-code/src/version.mjs @@ -1,5 +1,7 @@ /** - * This package's version, as `package.json` states it; a test holds them equal. + * This package's version, as `package.json` states it; a test holds them equal, + * and release-please writes both (the marker on the line below, and `extra-files` in + * `release-please-config.json`). * A constant, because `package.json` cannot be imported in a browser. */ -export const VERSION = '0.8.0'; +export const VERSION = '0.9.2'; // x-release-please-version diff --git a/studio/shell/prism/complete.mjs b/studio/shell/prism/complete.mjs new file mode 100644 index 00000000..e82be38c --- /dev/null +++ b/studio/shell/prism/complete.mjs @@ -0,0 +1,348 @@ +/** + * The draft form of `prism/spec/1`, and the step that completes it. + * + * A model's job is translation: it writes what the user said, which is a + * `title`, the `fields`, the ordered `rules` and the `otherwise` answer. + * Everything else a spec holds restates those or adds to them, so Prism derives + * it here, the same way every time: + * + * outcomes the answers the rules and `otherwise` give, in first-appearance order + * purpose one sentence built from the answers and the fields + * name from the title, as the session derives it + * examples the first request each rule decides, and one for `otherwise` + * properties guarantees read off the rules, each marked as proposed + * + * It also reads the few slips that have one meaning, and names each in a note: + * an `invalid` listed among the answers that nothing answers, a guarantee no + * request can meet, and a number field compared with a bare word that names + * another number field. + * + * A spec is a draft when it leaves out any of `purpose`, `outcomes`, + * `properties` or `examples`. A stored spec holds all four (Prism writes them, + * empty when there is nothing), so it is never completed again and a guarantee + * the user struck does not come back. A draft is still `prism/spec/1`: + * completing it gives an ordinary spec, and a spec that is already whole comes + * back as `validateSpec` gives it. + * + * Pure: no clock, no randomness, no files. The same input gives the same spec, + * and so the same canonical bytes and the same address. + */ +import { INVALID, PROPOSED, SpecError, counterexample, decodeRequest, describeConditions, describeProperty, describeRule, encodeRequest, holds, isProposed, judge, nameFromPurpose, respond, sampleRequests, sampleSize, unreachableRules, validateSpec } from './spec.mjs'; +import { canonicalJson, checkMembers, parseStrictJson } from './spec-file.mjs'; +import { STATEFUL_SCHEMA, statefulCounterexample } from './stateful.mjs'; + +export { PROPOSED, isProposed }; + +/** What a model need not write: Prism derives each when a draft leaves it out. */ +export const DERIVED_MEMBERS = Object.freeze(['purpose', 'outcomes', 'properties', 'examples']); +/** A draft with fewer guarantees than this gets proposals, up to this many in all. */ +export const GUARANTEES_WANTED = 3; +/** A draft with no examples gets at most this many. */ +export const EXAMPLES_WANTED = 6; + +const SAMPLE_LIMIT = 200000; + +const refuse = (message, where, rule) => { + throw new SpecError(message, where, rule); +}; + +const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v); +const listOf = (v) => (Array.isArray(v) ? v : []); +const words = (list, last) => (list.length <= 1 ? list.join('') : `${list.slice(0, -1).join(', ')} ${last} ${list.at(-1)}`); + +/** Whether a spec is a draft: a `prism/spec/1` spec that leaves out something Prism derives. */ +export const isDraft = (spec) => isObject(spec) && spec.schema !== STATEFUL_SCHEMA && DERIVED_MEMBERS.some((key) => spec[key] === undefined); + +/** The purpose of a draft that states none: what it answers, and from what. Always text a model can carry. */ +export function purposeFrom(outcomes, fields) { + const long = `Decides ${words(outcomes, 'or')} from ${words(fields, 'and')}.`; + return long.length <= 200 ? long : `Decides one of ${outcomes.length} answers from ${fields.length} fields.`; +} + +/** + * The name of a draft that states none: from the title when there is one, as + * the session reads `Title: sentence` (session.mjs), else from the purpose. + */ +export const nameFrom = (title, purpose) => (typeof title === 'string' && title.trim() ? nameFromPurpose(`${title}:`) : nameFromPurpose(purpose)); + +/** A rule or guarantee as its author wrote it: without the id and the sentence Prism adds. */ +function written(item, describe) { + const { id, says, ...rest } = item; + return says !== undefined && says !== describe(item) ? { ...rest, says } : rest; +} + +const propertyKey = (p) => JSON.stringify([p.kind, p.then, p.when]); + +/** + * Whether trying every candidate request settles what a conjunction can meet. + * The candidates are the edges of every comparison, so they reach every region + * the constants cut out; a chain of three or more number fields compared with + * each other can need three distinct values inside one region, which the edges + * do not always hold. Such a guarantee is never called empty. + */ +function settledBySample(spec, conditions) { + const compared = new Set(); + for (const c of conditions) { + if (isObject(c.value)) { + compared.add(c.field); + compared.add(c.value.field); + } + } + return compared.size <= 2 && sampleSize(spec) <= SAMPLE_LIMIT; +} + +/** + * Complete a spec. Takes JSON text or a value; returns + * `{ spec, draft, proposed, notes }`: + * + * - `spec`: the whole, validated spec, the one to store and seal. + * - `draft`: whether the input left out something Prism derives. + * - `proposed`: the ids of the guarantees Prism proposed. + * - `notes`: what Prism dropped or could not do, each a sentence to show. + * + * Throws `SpecError`, naming its rule, when the input is not a spec even so. + * A spec whose own guarantee or example the rules break is completed without + * proposals or examples: `checkSpec` says what is wrong with it. + */ +export function completeSpec(input) { + const raw = typeof input === 'string' ? parseStrictJson(input) : structuredClone(input); + if (isObject(raw) && raw.schema === STATEFUL_SCHEMA) { + checkMembers(raw); + return { spec: validateSpec(raw), draft: false, proposed: [], notes: [] }; + } + // The same strict reading spec.json gets: no member the schema does not define, whole numbers only. + checkMembers(raw); + canonicalJson(raw); + const draft = isDraft(raw); + const notes = []; + const work = { ...raw }; + + // A number is never compared with text, so a bare word that names a number field, where a number + // field is compared, has one meaning: that field. Measured with Qwen3 30B (#666), this was every + // refusal of a rules-only draft, six runs of thirty. It is read as the field, and named. + const numbers = new Set(listOf(work.fields).filter((f) => isObject(f) && f.kind === 'number' && typeof f.name === 'string').map((f) => f.name)); + // The comparison word has one meaning too: equality on a choice is `is`, and `is` on a number is `=`. + // Answers given as text are already read this way (`condition` in spec.mjs). Measured with Qwen3 30B + // on 2026-11-15: `=` and `==` on a choice refused two drafts of two, and `is not` on a number one of forty. + const choices = new Map(listOf(work.fields).filter((f) => isObject(f) && f.kind === 'choice' && typeof f.name === 'string' && Array.isArray(f.values)).map((f) => [f.name, f.values])); + const CHOICE_WORD = { '=': 'is', '==': 'is', '!=': 'is not' }; + const NUMBER_WORD = { is: '=', '==': '=', 'is not': '!=' }; + const readWord = (c) => { + if (!isObject(c) || typeof c.op !== 'string') return c; + const choice = choices.has(c.field) && choices.get(c.field).includes(c.value); + const number = numbers.has(c.field) && (typeof c.value === 'number' || numbers.has(c.value) || (isObject(c.value) && numbers.has(c.value.field))); + const word = choice ? CHOICE_WORD[c.op] : number ? NUMBER_WORD[c.op] : undefined; + if (!word) return c; + const value = isObject(c.value) ? c.value.field : c.value; + notes.push(`Read \`${c.field} ${c.op} ${value}\` as \`${c.field} ${word} ${value}\`: ${choice ? 'a choice is compared with `is` or `is not`' : 'a number is compared with `=` or `!=`'}.`); + return { ...c, op: word }; + }; + const readField = (item) => { + if (!isObject(item) || !Array.isArray(item.when)) return item; + const when = item.when.map(readWord).map((c) => { + if (!isObject(c) || !numbers.has(c.field) || typeof c.value !== 'string' || !numbers.has(c.value)) return c; + notes.push(`Read \`${c.field} ${c.op} "${c.value}"\` as a comparison with the field ${c.value}: a number is never compared with text.`); + return { ...c, value: { field: c.value } }; + }); + return { ...item, when }; + }; + if (Array.isArray(work.rules)) work.rules = work.rules.map(readField); + if (Array.isArray(work.properties)) work.properties = work.properties.map(readField); + const rules = listOf(work.rules).filter(isObject); + + if (draft && listOf(work.outcomes).length === 0) { + if (rules.length === 0) refuse('Give at least one rule.', 'rules', 'rules.none'); + if (typeof work.otherwise !== 'string' || !work.otherwise) refuse('Say which answer applies when no rule matches.', 'rules', 'rules.otherwise'); + const answers = [...new Set([...rules.map((r) => r.then), work.otherwise].filter((w) => typeof w === 'string'))]; + if (answers.includes(INVALID)) refuse('`invalid` is the answer Prism gives a malformed request; a rule or `otherwise` cannot answer it. Pick another word.', 'outcomes', 'outcomes.reserved'); + if (answers.length < 2) refuse(`Every rule and \`otherwise\` answer ${answers[0]}, so the app decides nothing. Give at least two answers.`, 'outcomes', 'outcomes.too-few'); + work.outcomes = answers; + } else if (listOf(work.outcomes).includes(INVALID)) { + // A model that lists `invalid` and never answers it meant the answer Prism already gives. + const answered = [...rules, ...listOf(work.properties).filter(isObject)].some((x) => x.then === INVALID) || work.otherwise === INVALID; + if (!answered) { + work.outcomes = work.outcomes.filter((o) => o !== INVALID); + notes.push('Dropped `invalid` from the answers: Prism already answers it for a malformed request, and no rule answers it.'); + } + } + if (draft && (work.purpose === undefined || work.purpose === null || work.purpose === '')) { + work.purpose = purposeFrom(listOf(work.outcomes).map(String), listOf(work.fields).filter(isObject).map((f) => String(f.name))); + } + if (draft && !work.name) work.name = nameFrom(work.title, work.purpose); + work.properties = listOf(work.properties); + work.examples = listOf(work.examples); + + let spec = validateSpec(work); + + // A guarantee about requests that cannot happen (a weight below the least weight) says nothing, + // and Lean would prove nothing by it. It is dropped and named, only when every request was tried. + if (spec.properties.length && sampleSize(spec) <= SAMPLE_LIMIT) { + const met = spec.properties.map(() => false); + for (const request of sampleRequests(spec, SAMPLE_LIMIT)) spec.properties.forEach((p, i) => (met[i] ||= p.when.every((c) => holds(c, request)))); + const empty = spec.properties.filter((p, i) => !met[i] && settledBySample(spec, p.when)); + if (empty.length) { + for (const p of empty) notes.push(`Dropped the guarantee "${p.kind} ${p.then} when ${describeConditions(p.when)}": no request meets its conditions, so it says nothing.`); + work.properties = work.properties.filter((_, i) => !empty.includes(spec.properties[i])); + spec = validateSpec(work); + } + } + + const sound = spec.properties.every((p) => counterexample(spec, p).request === null) && spec.examples.every((e) => respond(spec, new TextEncoder().encode(e.request)) === e.response); + if (!draft || !sound) return { spec, draft, proposed: [], notes }; + + // One pass over the candidate requests: what each rule decides, and what each choice is answered. + const total = sampleSize(spec); + const exhaustive = total <= SAMPLE_LIMIT; + const reach = spec.rules.map(() => ({ met: false, overridden: false, first: null })); + const index = new Map(spec.rules.map((r, i) => [r.id, i])); + let firstOtherwise = null; + const answered = new Map(); + // Past the limit nothing is proposed, so only the examples are read off the pass: the first request + // each rule decides. It then stops once every rule and `otherwise` has one, and keeps no other count. + let wanted = spec.rules.length + 1; + for (const request of sampleRequests(spec, SAMPLE_LIMIT)) { + const { outcome, rule } = judge(spec, request); + if (rule === null) { + if (firstOtherwise === null) wanted--; + firstOtherwise ??= encodeRequest(spec, request); + } else { + if (reach[index.get(rule)].first === null) wanted--; + reach[index.get(rule)].first ??= encodeRequest(spec, request); + } + if (!exhaustive) { + if (wanted === 0) break; + continue; + } + spec.rules.forEach((r, i) => { + if (!r.when.every((c) => holds(c, request))) return; + reach[i].met = true; + if (rule !== r.id) reach[i].overridden = true; + }); + for (const f of spec.fields) { + if (f.kind !== 'choice') continue; + const key = `${f.name} ${request[f.name]}`; + if (!answered.has(key)) answered.set(key, new Set()); + answered.get(key).add(outcome); + } + } + + const proposals = []; + if (spec.properties.length < GUARANTEES_WANTED) { + if (!exhaustive) { + notes.push(`No guarantee is proposed: the rules cut the requests into ${total} cases, more than the ${SAMPLE_LIMIT} Prism tries, so a proposal could not be checked against every one.`); + } else { + const candidates = []; + spec.rules.forEach((r, i) => { + if (reach[i].met && !reach[i].overridden) candidates.push({ kind: 'always', when: structuredClone(r.when), then: r.then, why: `${PROPOSED} from ${r.id}: no earlier rule overrides it.` }); + }); + for (const f of spec.fields) { + if (f.kind !== 'choice') continue; + for (const v of f.values) { + const got = answered.get(`${f.name} ${v}`); + for (const o of spec.outcomes) if (got && !got.has(o)) candidates.push({ kind: 'never', when: [{ field: f.name, op: 'is', value: v }], then: o, why: `${PROPOSED} from the rules: no request with ${f.name} ${v} is answered ${o}.` }); + } + } + const have = new Set(spec.properties.map(propertyKey)); + for (const candidate of candidates) { + if (spec.properties.length + proposals.length >= GUARANTEES_WANTED) break; + if (have.has(propertyKey(candidate))) continue; + const trial = validateSpec({ ...work, properties: [...work.properties, ...proposals, candidate] }); + if (counterexample(trial, trial.properties.at(-1)).request !== null) continue; + have.add(propertyKey(candidate)); + proposals.push(candidate); + } + } + } + if (proposals.length) work.properties = [...work.properties, ...proposals]; + + if (spec.examples.length === 0) { + const decided = spec.rules.map((r, i) => (reach[i].first === null ? null : { request: reach[i].first, response: r.then })).filter(Boolean); + const last = firstOtherwise === null ? [] : [{ request: firstOtherwise, response: spec.otherwise }]; + work.examples = [...decided.slice(0, EXAMPLES_WANTED - last.length), ...last]; + } + + spec = validateSpec(work); + return { spec, draft, proposed: spec.properties.filter(isProposed).map((p) => p.id), notes }; +} + +/** + * Check a spec as the journey does, in one call: complete it, then look for a + * guarantee the rules break and an example they answer differently. Returns + * + * { ok, spec, draft, proposed, notes, refusal, broken, examples } + * + * - `refusal`: `{ rule, where, message }` when the input is not a spec, else null. + * - `broken`: for each guarantee the rules break, the guarantee and the rule + * that decides against it as their author wrote them, with the request that + * shows the conflict and what it answers (`rule` is null when `otherwise` decided). + * - `examples`: for each example the rules answer differently, the example and + * what the rules answer. + * + * `repairMessage` turns a result that is not ok into what to tell the author. + */ +export function checkSpec(input) { + let done; + try { + done = completeSpec(input); + } catch (error) { + if (!(error instanceof SpecError)) throw error; + return { ok: false, spec: null, draft: false, proposed: [], notes: [], refusal: { rule: error.rule ?? null, where: error.where ?? null, message: error.message }, broken: [], examples: [] }; + } + const { spec } = done; + const notes = [...done.notes]; + const broken = []; + const examples = []; + if (spec.schema === STATEFUL_SCHEMA) { + for (const p of spec.properties) { + const found = statefulCounterexample(spec, p); + if (found.steps !== null) broken.push({ id: p.id, guarantee: written(p, () => undefined), steps: found.steps, request: found.steps.join(';'), answer: found.outcome ?? null, state: found.state ?? null, rule: null }); + } + return { ok: broken.length === 0, ...done, notes, refusal: null, broken, examples }; + } + for (const p of spec.properties) { + const found = counterexample(spec, p); + if (found.request === null) continue; + const rule = found.rule ? spec.rules.find((r) => r.id === found.rule) : null; + broken.push({ id: p.id, guarantee: written(p, describeProperty), request: found.request, answer: found.outcome, ruleId: found.rule, rule: rule ? written(rule, describeRule) : null }); + } + for (const e of spec.examples) { + const answer = respond(spec, new TextEncoder().encode(e.request)); + if (answer === e.response) continue; + const request = decodeRequest(spec, e.request); + examples.push({ example: e, answer, ruleId: request ? judge(spec, request).rule : null, malformed: !request }); + } + const dead = unreachableRules(validateSpec({ ...spec, properties: [], examples: [] })); + if (dead.length) notes.push(`${dead.join(', ')} never decides anything: an earlier rule always matches first, or its conditions cannot all hold.`); + return { ok: broken.length === 0 && examples.length === 0, ...done, notes, refusal: null, broken, examples }; +} + +/** + * What to tell the author of a spec the checker refused, or null when it was + * accepted. A broken guarantee is named as the JSON its author wrote, beside + * the rule that decides against it and the request that shows the conflict, + * with the two ways out: a message that only says a guarantee "does not hold" + * was measured to be written back unchanged. Any other refusal is given in the + * checker's own words. + */ +export function repairMessage(result) { + if (!result || result.ok) return null; + const again = 'Then write the whole spec again with nothing else changed.'; + if (result.refusal) { + const where = result.refusal.where ? ` (at ${result.refusal.where})` : ''; + return `Prism checked the spec and refused it:\n- ${result.refusal.message}${where}\nFix exactly that. ${again}`; + } + const lines = []; + for (const b of result.broken.slice(0, 6)) { + const by = b.steps + ? `the session \`${b.request}\` ${b.answer ? `ends answering ${b.answer}` : `reaches the state ${b.state}`}` + : `the request \`${b.request}\` answers ${b.answer}, ${b.rule ? `by the rule ${JSON.stringify(b.rule)}` : `because no rule matches and \`otherwise\` is ${b.answer}`}`; + lines.push(`- The guarantee ${JSON.stringify(b.guarantee)} is false: ${by}.`); + } + for (const e of result.examples.slice(0, 6)) { + lines.push(`- The example ${JSON.stringify(e.example)} is wrong: ${e.malformed ? 'it is not a request (the fields in order, separated by single spaces), so the answer is invalid' : `the rules answer ${e.answer}`}.`); + } + const how = []; + if (result.broken.length) how.push('For each false guarantee, fix it in one of two ways: delete that guarantee from "properties", or change the rules so that request gets the answer the guarantee names.'); + if (result.examples.length) how.push('For each wrong example, delete it from "examples" or give it the answer the rules give.'); + return `Prism checked the spec and refused it:\n${lines.join('\n')}\n${how.join(' ')} ${again}`; +} diff --git a/studio/shell/prism/render-stateful.mjs b/studio/shell/prism/render-stateful.mjs new file mode 100644 index 00000000..e0fe5145 --- /dev/null +++ b/studio/shell/prism/render-stateful.mjs @@ -0,0 +1,523 @@ +/** + * Render a `prism/spec/2` spec (stateful.mjs) into the LexLean model of a text + * application that keeps state, its proofs, its acceptance vectors and SPEC.md. + * + * The model is a state machine: a `State` structure of `Nat` values (a choice + * is its code), `initial`, and for each action two total functions of the + * state and the action's inputs, `after` (the next state, each field + * its own `if` chain) and `reply` (the answer's code, one `if` + * chain), over the same rule guards: a rule's conditions, and that each of + * its changes keeps its number within bounds. Every guard is a `Nat` comparison, so each property + * is proved by `linear_arithmetic`, as for prism/spec/1. + * + * The text profile answers one request with one response and keeps nothing, + * so a session is one request: its steps separated by `;`, replayed from + * `initial` by the guest. The answer is the last step's outcome and the state + * it leaves. Every state the guest computes is reachable, so what Lean proves + * of reachable states holds of every answer. The state machine does not + * depend on that projection: the session world (`hologram:guest/core-wasm@2`, + * #629, with its profile in #630) can run the same `after` and `reply` one + * step at a time, and the spec and its seal stay the same. + * + * Nothing here reads anything but the spec, so the same spec gives the same + * bytes. + */ +import { INVALID, MAX_DIGITS } from './spec.mjs'; +import { LEAN_RESERVED, QP, camel, conjunction, describedBy, hex, moduleText, pascal, quote, stem, withAxioms } from './render.mjs'; +import { + SESSION_BYTES, + act, + encodeStep, + holdsIn, + initialState, + inputCandidates, + reachableStates, + respondSession, + sessionLimits, +} from './stateful.mjs'; + +const FIXED = [ + 'State', 'Turn', 'Move', 'byteAt', 'digitsValue', 'parseDigits', 'parseNumber', 'sliceOf', 'tokenEnd', 'moveAt', 'decodeStep', 'applyMove', 'replay', + 'initial', 'digitByte', 'decimalOf', 'encodeAnswer', 'stateText', 'dispatch', 'application', 'startInBounds', 'breaksStartInBounds', + 'turnState', 'turnAnswer', 'moveAction', 'moveNext', 'moveMore', +]; + +/** Every identifier the model and its proofs use, derived once so the model, the vectors and SPEC.md agree. */ +export function statefulNames(spec) { + const used = new Set(FIXED); + const claim = (base) => { + let name = base; + for (let i = 2; used.has(name) || LEAN_RESERVED.has(name); i++) name = `${base}${i}`; + used.add(name); + return name; + }; + const module = pascal(spec.name) || 'App'; + const width = Math.max(0, ...spec.actions.map((a) => a.inputs.length)); + const args = Array.from({ length: width }, (_, i) => claim(`moveArg${i + 1}`)); + const state = {}; + for (const f of spec.state) { + const id = claim(camel(f.name)); + state[f.name] = { id, choices: {} }; + if (f.kind === 'choice') for (const v of f.values) state[f.name].choices[v] = claim(`${id}${pascal(v)}`); + } + const answers = {}; + for (const o of spec.outcomes) answers[o] = claim(`answer${pascal(o)}`); + const actions = {}; + for (const [ai, a] of spec.actions.entries()) { + const P = pascal(a.name); + const inputs = {}; + for (const f of a.inputs) { + const id = claim(camel(`${a.name}-${f.name}`)); + const bounded = f.kind === 'choice' || f.min !== undefined || f.max !== undefined; + inputs[f.name] = { id, parse: bounded ? claim(`parse${P}${pascal(f.name)}`) : 'parseNumber', choices: {} }; + if (f.kind === 'choice') for (const v of f.values) inputs[f.name].choices[v] = claim(`${id}${pascal(v)}`); + } + actions[a.name] = { + code: ai + 1, + after: claim(`after${P}`), + reply: claim(`reply${P}`), + decode: a.inputs.map((_, j) => claim(`decode${P}${j + 1}`)), + keepsBounds: claim(`${camel(a.name)}KeepsBounds`), + inputs, + }; + } + const properties = {}; + for (const p of spec.properties) { + const s = p.id.toLowerCase().replace(/[^a-z0-9]/g, ''); + properties[p.id] = p.action + ? { theorems: [claim(`${s}Holds`)] } + : { theorems: [claim(`${s}AtStart`), ...spec.actions.map((a) => claim(`${s}KeptBy${pascal(a.name)}`))] }; + } + return { module, proofs: `${module}Proofs`, prefix: `Prism${module}`, args, state, answers, actions, properties, stateful: true }; +} + +/** + * The axioms each theorem is expected to rest on, as Lean observed them for the dinner-seats + * example: a bounds theorem, over every field of the state, uses all three standard axioms; a + * property theorem uses two. A verify that observes another set still rewrites it (engine.mjs), + * and anything outside these three is refused. + */ +const BOUNDS_AXIOMS = '[Classical.choice, Quot.sound, propext]'; + +const NONE = (t) => `(ctor Option.none [${t}])`; +const SOME = (t, v) => `(ctor Option.some [${t}] ${v})`; +const LEN = (s) => `(Foundation.Bytes::byteLength ${s})`; +const SPACE = 32; +const SEMICOLON = 59; + +/** + * A condition as a `Bool` term. `subject(field)` is the expression a name + * stands for (a state value or an input), and `constant(field, value)` the + * code of a choice. + */ +function condition(c, subject, constant) { + const left = subject(c.field); + if (c.op === 'is') return `(${left} =? (${constant(c.field, c.value)}))`; + if (c.op === 'is not') return `(not (${left} =? (${constant(c.field, c.value)})))`; + const right = typeof c.value === 'object' ? subject(c.value.field) : String(c.value); + switch (c.op) { + case '<': return `(${left} ': return `(${right} =': return `(${right} <=? ${left})`; + case '=': return `(${left} =? ${right})`; + case '!=': return `(not (${left} =? ${right}))`; + default: throw new Error(`unknown op ${c.op}`); + } +} + +/** The guard that a change keeps its number within bounds; null when it always does. */ +function changeGuard(spec, c, subject) { + const f = spec.state.find((x) => x.name === c.field); + if (f.kind === 'choice' || (c.op === 'set' && typeof c.value === 'number')) return null; + const v = typeof c.value === 'object' ? subject(c.value.field) : String(c.value); + const old = subject(c.field); + const min = f.min ?? 0; + if (c.op === 'set') return conjunction([...(min > 0 ? [`(${min} <=? ${v})`] : []), `(${v} <=? ${f.max})`]); + if (c.op === 'add') return `((${old} + ${v}) <=? ${f.max})`; + return min > 0 ? `((${v} + ${min}) <=? ${old})` : `(${v} <=? ${old})`; +} + +/** The value a state field takes after a rule. */ +function changed(spec, rule, field, subject, constant) { + const c = rule.change.find((x) => x.field === field.name); + if (!c) return subject(field.name); + if (field.kind === 'choice') return `(${constant(field.name, c.value)})`; + const v = typeof c.value === 'object' ? subject(c.value.field) : String(c.value); + if (c.op === 'set') return v; + if (c.op === 'add') return `(${subject(field.name)} + ${v})`; + return `(prim subtract ${subject(field.name)} ${v} : Nat)`; +} + +const ruleGuard = (spec, rule, subject, constant) => + conjunction([...rule.when.map((c) => condition(c, subject, constant)), ...rule.change.map((c) => changeGuard(spec, c, subject)).filter(Boolean)]) || 'true'; + +/** Subjects and constants inside the app module: `state` is the parameter, inputs are named parameters. */ +function scope(spec, n, action, { state = 'state', q = (x) => x } = {}) { + const inputs = action ? n.actions[action.name].inputs : {}; + const subject = (field) => (n.state[field] ? `(project ${state} ${n.state[field].id})` : inputs[field].id); + const constant = (field, value) => q(n.state[field] ? n.state[field].choices[value] : inputs[field].choices[value]); + return { subject, constant }; +} + +/** The model's declarations, in order. */ +export function statefulDeclarations(spec, n = statefulNames(spec), { specAddress = null } = {}) { + const out = []; + const def = (name, parameters, result, body, axioms = null, recursive = null) => out.push({ name, kind: 'definition', parameters, result, body, axioms, ...(recursive ? { recursive } : {}) }); + const width = n.args.length; + + for (const f of spec.state) if (f.kind === 'choice') f.values.forEach((v, i) => def(n.state[f.name].choices[v], [], 'Nat', String(i))); + for (const a of spec.actions) for (const f of a.inputs) if (f.kind === 'choice') f.values.forEach((v, i) => def(n.actions[a.name].inputs[f.name].choices[v], [], 'Nat', String(i))); + spec.outcomes.forEach((o, i) => def(n.answers[o], [], 'Nat', String(i))); + + out.push({ name: 'State', kind: 'structure', fields: spec.state.map((f) => `{name: ${n.state[f.name].id}, type: Nat}`) }); + out.push({ name: 'Turn', kind: 'structure', fields: ['{name: turnState, type: State}', '{name: turnAnswer, type: Nat}'] }); + out.push({ name: 'Move', kind: 'structure', fields: ['{name: moveAction, type: Nat}', '{name: moveNext, type: Nat}', '{name: moveMore, type: Nat}', ...n.args.map((x) => `{name: ${x}, type: Nat}`)] }); + + def('initial', [], 'State', `(record State {${spec.state.map((f) => `${n.state[f.name].id} := ${f.kind === 'choice' ? `(${n.state[f.name].choices[f.start]})` : String(f.start)}`).join(', ')}})`); + + // The actions: one `if` chain of rule guards for the next state, and the same chain for the answer. + for (const a of spec.actions) { + const names = n.actions[a.name]; + const { subject, constant } = scope(spec, n, a); + const params = ['state : State', ...a.inputs.map((f) => `${names.inputs[f.name].id} : Nat`)]; + // One record whose every field is an `if` chain, never an `if` of records: the proof form + // simplifies before it splits, so a projection of a record inside an `if` would stay opaque. + // A field's chain runs to the last rule that changes it; an earlier rule that leaves it keeps it. + const valueAfter = (f) => { + const last = a.rules.findLastIndex((r) => r.change.some((c) => c.field === f.name)); + return a.rules.slice(0, last + 1).reduceRight((rest, r) => `(if ${ruleGuard(spec, r, subject, constant)} then ${changed(spec, r, f, subject, constant)} else ${rest})`, subject(f.name)); + }; + def(names.after, params, 'State', `(record State {${spec.state.map((f) => `${n.state[f.name].id} := ${valueAfter(f)}`).join(', ')}})`); + def(names.reply, params, 'Nat', a.rules.reduceRight((rest, r) => `(if ${ruleGuard(spec, r, subject, constant)} then (${n.answers[r.then]}) else ${rest})`, `(${n.answers[a.otherwise]})`)); + } + + // Reading a session: bytes, never text, as prism/spec/1 reads a request (render.mjs). + def('byteAt', ['s : Bytes', 'i : Nat'], '(Option Nat)', `(match (prim index s i : (Option UInt8)) + | Option.none => ${NONE('Nat')} + | Option.some b => ${SOME('Nat', '(prim to_nat b : Nat)')})`, QP); + def('digitsValue', ['s : Bytes', 'i : Nat', 'acc : Nat', 'fuel : Nat'], '(Option Nat)', `(match fuel + | Nat.zero => ${SOME('Nat', 'acc')} + | Nat.succ rest => (match (byteAt s i) + | Option.none => ${NONE('Nat')} + | Option.some d => (if ((d ${NONE('Nat')} + | Option.some lead => (if ((lead =? 48) && (1 `(if (prim equal value ${hex(v)} : Bool) then ${SOME('Nat', `(${input.choices[v]})`)} else ${rest})`, NONE('Nat'))); + } else if (input.parse !== 'parseNumber') { + let accept = SOME('Nat', 'parsed'); + if (f.max !== undefined) accept = `(if (${f.max} 0) accept = `(if (parsed ${NONE('Nat')}\n | Option.some parsed => ${accept})`, QP); + } + } + } + def('sliceOf', ['s : Bytes', 'start : Nat', 'count : Nat'], 'Bytes', `(match (prim slice s start count : (Option Bytes))\n | Option.none => 0x\n | Option.some part => part)`); + // Where a token ends: the next space or `;`, or the end of the session. + def('tokenEnd', ['s : Bytes', 'i : Nat', 'fuel : Nat'], 'Nat', `(match fuel + | Nat.zero => i + | Nat.succ rest => (match (byteAt s i) + | Option.none => i + | Option.some d => (if ((d =? ${SPACE}) || (d =? ${SEMICOLON})) then i else (tokenEnd s (i + 1) rest))))`, QP, 'fuel'); + // A step ends at the end of the session, or at a `;` with another step after it. + const argParams = n.args.map((x) => `${x} : Nat`); + const move = (more, next) => SOME('Move', `(record Move {moveAction := action, moveNext := ${next}, moveMore := ${more}${n.args.map((x) => `, ${x} := ${x}`).join('')}})`); + def('moveAt', ['s : Bytes', 'e : Nat', 'action : Nat', ...argParams], '(Option Move)', `(if (e =? ${LEN('s')}) then ${move(0, 'e')} else (match (byteAt s e) + | Option.none => ${NONE('Move')} + | Option.some d => (if ((d =? ${SEMICOLON}) && ((e + 1) Array.from({ length: j }, (_, i) => `v${i + 1}`); + const finish = (values) => `(moveAt s e ${names.code}${Array.from({ length: width }, (_, i) => ` ${values[i] ?? '0'}`).join('')})`; + for (let j = k; j >= 1; j--) { + const input = names.inputs[a.inputs[j - 1].name]; + const next = j === k ? finish(vs(k)) : `(${names.decode[j]} s e ${vs(j).join(' ')})`; + def(names.decode[j - 1], ['s : Bytes', 'at : Nat', ...vs(j - 1).map((v) => `${v} : Nat`)], '(Option Move)', `(match (byteAt s at) + | Option.none => ${NONE('Move')} + | Option.some d => (if (d =? ${SPACE}) then (let e : Nat := (tokenEnd s (at + 1) ${LEN('s')}); (match (${input.parse} (sliceOf s (at + 1) (prim subtract e (at + 1) : Nat))) + | Option.none => ${NONE('Move')} + | Option.some v${j} => ${next})) else ${NONE('Move')}))`, QP); + } + } + const byWord = spec.actions.reduceRight((rest, a) => { + const names = n.actions[a.name]; + const go = a.inputs.length ? `(${names.decode[0]} s e)` : `(moveAt s e ${names.code}${' 0'.repeat(width)})`; + return `(if (prim equal word ${hex(a.name)} : Bool) then ${go} else ${rest})`; + }, NONE('Move')); + def('decodeStep', ['s : Bytes', 'i : Nat'], '(Option Move)', `(let e : Nat := (tokenEnd s i ${LEN('s')}); (let word : Bytes := (sliceOf s i (prim subtract e i : Nat)); ${byWord}))`, QP); + const applied = spec.actions.reduceRight((rest, a) => { + const names = n.actions[a.name]; + const call = (fn) => `(${fn} state${a.inputs.map((_, i) => ` (project m ${n.args[i]})`).join('')})`; + return `(if ((project m moveAction) =? ${names.code}) then (record Turn {turnState := ${call(names.after)}, turnAnswer := ${call(names.reply)}}) else ${rest})`; + }, '(record Turn {turnState := state, turnAnswer := 0})'); + def('applyMove', ['state : State', 'm : Move'], 'Turn', applied); + def('replay', ['s : Bytes', 'i : Nat', 'state : State', 'fuel : Nat'], '(Option Turn)', `(match fuel + | Nat.zero => ${NONE('Turn')} + | Nat.succ rest => (match (decodeStep s i) + | Option.none => ${NONE('Turn')} + | Option.some m => (if ((project m moveMore) =? 0) then ${SOME('Turn', '(applyMove state m)')} else (replay s (project m moveNext) (project (applyMove state m) turnState) rest))))`, QP, 'fuel'); + + // The answer: the outcome, then each state value as ` name=value`. + def('digitByte', ['d : Nat'], 'Bytes', Array.from({ length: 9 }, (_, i) => i).reduceRight((rest, i) => `(if (d =? ${i}) then ${hex(String(i))} else ${rest})`, hex('9'))); + def('decimalOf', ['value : Nat', 'fuel : Nat'], 'Bytes', `(match fuel + | Nat.zero => 0x + | Nat.succ rest => (if (value `(if (code =? (${n.answers[o]})) then ${hex(o)} else ${rest})`, hex(INVALID))); + const valueText = (f) => { + const subject = `(project state ${n.state[f.name].id})`; + if (f.kind === 'number') return `(decimalOf ${subject} ${MAX_DIGITS + 1})`; + return f.values.reduceRight((rest, v) => `(if (${subject} =? (${n.state[f.name].choices[v]})) then ${hex(v)} else ${rest})`, '0x'); + }; + def('stateText', ['state : State'], 'Bytes', spec.state.reduce((acc, f) => `(prim append ${acc} (prim append ${hex(` ${f.name}=`)} ${valueText(f)} : Bytes) : Bytes)`, '0x')); + + const limits = sessionLimits(spec); + def('dispatch', ['value : Bytes'], 'Bytes', `(if (${limits.requestMaximum} ${hex(INVALID)} + | Option.some turn => (prim append (encodeAnswer (project turn turnAnswer)) (stateText (project turn turnState)) : Bytes)))`, QP); + + const vectors = statefulAcceptanceVectors(spec); + const root = `${n.prefix}.${n.module}.dispatch`; + const AV = 'Foundation.View.Text.V1.Model::AcceptanceVector'; + const vectorList = vectors.reduceRight((rest, v) => `(cons (record ${AV} {request := ${hex(v.bytes)}, response := ${hex(v.response)}}) ${rest})`, `(nil ${AV})`); + const view = `(record Foundation.View.Text.V1.Model::TextView {title := ${quote(spec.title)}, heading := ${quote(spec.title)}, inputLabel := ${quote('Session: steps separated by ;')}, submitLabel := "Run", outputLabel := "Answer and state", inputError := "Invalid session", responseError := "Invalid response"})`; + def( + 'application', + [], + 'Foundation.View.Text.V1.Model::TextApplication', + `(record Foundation.View.Text.V1.Model::TextApplication {profile := "prismpm/text-application/1", name := ${quote(stem(spec.title))}, cargoName := ${quote(`prism-${spec.name}`)}, cargoVersion := "0.1.0", cargoDescription := ${quote(describedBy(spec, specAddress))}, cargoRepository := "https://github.com/UOR-Foundation/PrismPM", cargoHomepage := "https://github.com/UOR-Foundation/PrismPM", libraryRoots := (cons ${quote(root)} (nil String)), acceptanceVectors := ${vectorList}, entryRoot := ${quote(root)}, coreContract := "hologram:guest/core-wasm@1", requestMaximum := (${limits.requestMaximum} : UInt32), responseMaximum := (${limits.responseMaximum} : UInt32), guestAllocationMaximum := (${limits.guestAllocationMaximum} : UInt32), capabilitiesEmpty := true, fatArchive := true, primaryLayer := (0 : UInt8), viewLayer := (1 : UInt8), view := ${view}})`, + ); + return out; +} + +/** The state's bounds as `Bool` terms over `subject`. */ +const stateBounds = (spec, subject) => + spec.state.flatMap((f) => (f.kind === 'choice' ? [`(${subject(f.name)} 0 ? [`(${f.min} <=? ${subject(f.name)})`] : []), `(${subject(f.name)} <=? ${f.max})`])); +/** The bounds a decoded input satisfies. */ +const inputBounds = (action, subject) => + action.inputs.flatMap((f) => (f.kind === 'choice' ? [`(${subject(f.name)} 0 ? [`(${f.min} <=? ${subject(f.name)})`] : []), ...(f.max !== undefined ? [`(${subject(f.name)} <=? ${f.max})`] : [])])); +/** A state property as one `Bool` term: `always` is its conditions, `never` their negation. */ +const invariant = (p, subject, constant) => { + const all = conjunction(p.when.map((c) => condition(c, subject, constant))); + return p.kind === 'always' ? all : `(not ${all})`; +}; + +/** + * The proofs module. Each state property is proved by induction over the + * steps of a session, as two kinds of theorem: it holds at the start, and + * every action keeps it, from any state within bounds where every state + * property holds. Every action keeps the bounds, and the start is within + * them. Each action property is proved for every such state, so for every + * reachable one. Lean checks each theorem; that the theorems together cover + * every reachable state is the induction, stated here and in SPEC.md. + */ +export function statefulProofDeclarations(spec, n = statefulNames(spec)) { + const out = []; + const q = (name) => `${n.module}::${name}`; + const constants = [...Object.values(n.answers), ...Object.values(n.state).flatMap((f) => Object.values(f.choices)), ...Object.values(n.actions).flatMap((a) => Object.values(a.inputs).flatMap((f) => Object.values(f.choices)))]; + const invariants = spec.properties.filter((p) => !p.action); + const theorem = (name, parameters, body, uses, axioms = QP) => { + const breaks = `breaks${pascal(name)}`; + out.push({ name: breaks, kind: 'definition', parameters, result: 'Bool', body, axioms: null }); + const args = parameters.map((p) => p.split(' : ')[0]).join(' '); + out.push({ name, kind: 'theorem', parameters, statement: `((${breaks}${args ? ` ${args}` : ''}) = false)`, unfold: [...new Set([breaks, ...uses.map(q), ...constants.map(q)])].sort(), axioms }); + }; + const atStart = scope(spec, n, null, { state: `(${q('initial')})`, q }); + theorem('startInBounds', [], `(not ${conjunction(stateBounds(spec, atStart.subject))})`, ['initial'], BOUNDS_AXIOMS); + for (const p of invariants) theorem(n.properties[p.id].theorems[0], [], `(not ${invariant(p, atStart.subject, atStart.constant)})`, ['initial']); + for (const a of spec.actions) { + const names = n.actions[a.name]; + const params = [`state : ${q('State')}`, ...a.inputs.map((f) => `${names.inputs[f.name].id} : Nat`)]; + const call = `(${q(names.after)} state${a.inputs.map((f) => ` ${names.inputs[f.name].id}`).join('')})`; + const before = scope(spec, n, a, { q }); + const after = scope(spec, n, a, { state: call, q }); + const hypotheses = [...stateBounds(spec, before.subject), ...inputBounds(a, before.subject)]; + theorem(names.keepsBounds, params, conjunction([...hypotheses, `(not ${conjunction(stateBounds(spec, after.subject))})`]), [names.after], BOUNDS_AXIOMS); + const held = invariants.map((p) => invariant(p, before.subject, before.constant)); + for (const p of invariants) { + theorem(n.properties[p.id].theorems[1 + spec.actions.indexOf(a)], params, conjunction([...hypotheses, ...held, `(not ${invariant(p, after.subject, after.constant)})`]), [names.after]); + } + for (const p of spec.properties.filter((x) => x.action === a.name)) { + const answer = `((${q(names.reply)} state${a.inputs.map((f) => ` ${names.inputs[f.name].id}`).join('')}) =? (${q(n.answers[p.then])}))`; + theorem(n.properties[p.id].theorems[0], params, conjunction([...hypotheses, ...held, ...p.when.map((c) => condition(c, before.subject, before.constant)), p.kind === 'never' ? answer : `(not ${answer})`]), [names.reply]); + } + } + return out; +} + +/** The app module. */ +export function renderStatefulModel(spec, { axioms = {}, specAddress = null } = {}) { + const n = statefulNames(spec); + return moduleText(n.module, ['Foundation.Bytes', 'Foundation.View.Text.V1.Model'], withAxioms(statefulDeclarations(spec, n, { specAddress }), axioms)); +} + +/** The proofs module. Never null: the bounds are always proved, stated properties or not. */ +export function renderStatefulProofs(spec, { axioms = {} } = {}) { + const n = statefulNames(spec); + return moduleText(n.proofs, [n.module], withAxioms(statefulProofDeclarations(spec, n), axioms)); +} + +/** + * The acceptance vectors: every prefix of every example session, one session + * per distinct way the rules decide from the reachable states sampled, and + * the malformed sessions every app must refuse, each answered by the + * evaluator. One vector is exactly the guest allocation bound long. + */ +export function statefulAcceptanceVectors(spec) { + const enc = (s) => new TextEncoder().encode(s); + const out = []; + const seen = new Set(); + const add = (bytes, why) => { + const key = Buffer.from(bytes).toString('hex'); + if (seen.has(key)) return; + seen.add(key); + out.push({ bytes, request: new TextDecoder().decode(bytes), response: respondSession(spec, bytes), why }); + }; + const session = (steps) => steps.join(';'); + for (const e of spec.examples) for (let i = 1; i <= e.steps.length; i++) if (session(e.steps.slice(0, i)).length <= SESSION_BYTES) add(enc(session(e.steps.slice(0, i))), 'example'); + + const conds = [...spec.actions.flatMap((a) => a.rules.flatMap((r) => r.when)), ...spec.properties.flatMap((p) => p.when)]; + const shapes = new Set(); + let decided = 0; + for (const { state, steps } of reachableStates(spec, 400)) { + for (const a of spec.actions) { + for (const inputs of inputCandidates(spec, a)) { + const r = act(spec, state, a, inputs); + const env = { ...state, ...inputs }; + const shape = `${a.name}|${r.rule}|${conds.map((c) => (env[c.field] === undefined || (typeof c.value === 'object' && env[c.value.field] === undefined) ? '-' : holdsIn(c, env) ? 1 : 0)).join('')}`; + if (shapes.has(shape)) continue; + shapes.add(shape); + const text = session([...steps, encodeStep(a, inputs)]); + if (text.length > SESSION_BYTES) continue; + add(enc(text), r.rule ? `decided by ${r.rule}` : `${a.name} otherwise`); + if (++decided >= 32) break; + } + if (decided >= 32) break; + } + if (decided >= 32) break; + } + + const { requestMaximum, guestAllocationMaximum } = sessionLimits(spec); + const first = spec.actions[0]; + const valid = encodeStep(first, inputCandidates(spec, first)[0] ?? {}); + add(enc(''), 'empty session'); + add(Uint8Array.of(0xff), 'not UTF-8'); + add(enc('unknown'), 'not an action'); + add(enc(`${valid};`), 'a trailing semicolon'); + add(enc(`${valid};;${valid}`), 'an empty step'); + add(enc(` ${valid}`), 'a leading space'); + add(enc(`${valid} extra`), 'an extra input'); + for (const a of spec.actions) { + const parts = encodeStep(a, inputCandidates(spec, a)[0] ?? {}).split(' '); + if (parts.length > 1) { + add(enc(parts.slice(0, -1).join(' ')), `${a.name} with an input missing`); + add(enc(parts.join(' ')), `${a.name} with two spaces`); + } + a.inputs.forEach((f, i) => { + const with_ = (v) => enc(parts.map((p, j) => (j === i + 1 ? v : p)).join(' ')); + if (f.kind === 'choice') add(with_('unknown'), `${a.name} ${f.name} not a choice`); + else { + add(with_('07'), `${a.name} ${f.name} with a leading zero`); + add(with_('-1'), `${a.name} ${f.name} negative`); + add(with_('1'.padEnd(19, '0')), `${a.name} ${f.name} with 19 digits`); + add(with_('x'), `${a.name} ${f.name} not a number`); + if (f.min !== undefined && f.min > 0) add(with_(String(f.min - 1)), `${a.name} ${f.name} below its minimum`); + if (f.max !== undefined) add(with_(String(f.max + 1)), `${a.name} ${f.name} above its maximum`); + } + }); + } + add(enc('x'.repeat(requestMaximum)), 'exactly the request bound'); + add(enc('x'.repeat(requestMaximum + 1)), 'one byte over the request bound'); + add(enc('x'.repeat(guestAllocationMaximum)), 'exactly the guest allocation bound'); + return out; +} + +/** SPEC.md for a stateful app, in the OpenSpec format, each requirement marked proved or tested. */ +export function renderStatefulSpecDocument(spec, status = {}) { + const n = statefulNames(spec); + const badge = (id) => ({ proved: 'proved by Lean for every reachable state', failing: 'not proved: see the counterexample', tested: 'tested only' })[status.properties?.[id]] ?? 'to be proved by Lean for every reachable state'; + const because = (why) => (why ? `, because ${why.replace(/[.]$/, '')}` : ''); + const accepts = (f) => (f.kind === 'choice' ? f.values.map((v) => `\`${v}\``).join(', ') : `whole number${f.min !== undefined ? ` from ${f.min}` : ''}${f.max !== undefined ? ` up to ${f.max}` : ''}`); + const start = initialState(spec); + const lines = [ + `# ${spec.name} Specification`, + '', + '', + '', + '## Purpose', + '', + `${spec.title}: ${spec.purpose.replace(/[.]?$/, '.')}`, + '', + '## Requirements', + '', + '### Requirement: The state stays within its bounds', + '', + `The app SHALL keep ${spec.state.map((f) => `\`${f.name}\` ${f.kind === 'choice' ? `one of ${accepts(f)}` : `from ${f.min ?? 0} up to ${f.max}`}`).join(', ')}, starting at ${spec.state.map((f) => `\`${f.name}=${start[f.name]}\``).join(', ')}.`, + '', + `Verified: proved by Lean (theorems \`startInBounds\`, ${spec.actions.map((a) => `\`${n.actions[a.name].keepsBounds}\``).join(', ')}).`, + '', + ...spec.properties.flatMap((p) => [ + `### Requirement: ${p.id} ${p.says.replace(/[.]$/, '')}`, + '', + `${p.says.replace(/[.]$/, '')}${because(p.why)}.`, + '', + `Verified: ${badge(p.id)} (${p.id}, ${n.properties[p.id].theorems.map((t) => `\`${t}\``).join(', ')}).`, + '', + ]), + ...spec.actions.flatMap((a) => [ + `### Requirement: Action ${a.name}`, + '', + `The app SHALL take \`${[a.name, ...a.inputs.map((f) => `<${f.name}>`)].join(' ')}\`${a.means ? `, which ${a.means.replace(/[.]$/, '')}` : ''}, and try its rules in order; the first whose conditions hold and whose changes keep the state within bounds SHALL decide. Otherwise it SHALL answer \`${a.otherwise}\` and change nothing${because(a.otherwiseWhy)}.`, + '', + ...a.rules.map((r) => `- ${r.id}: ${r.says}${r.why ? ` (${r.why.replace(/[.]$/, '')})` : ''}`), + ...(a.rules.length ? [''] : []), + ...a.inputs.map((f) => `- \`${f.name}\`: ${accepts(f)}${f.means ? `; ${f.means}` : ''}`), + ...(a.inputs.length ? [''] : []), + 'Verified: tested by the acceptance vectors.', + '', + ]), + '### Requirement: Sessions and answers', + '', + `The app SHALL read a session as its steps separated by \`;\`, each an action and its inputs separated by single spaces, at most ${SESSION_BYTES} bytes, replay it from the start state, and answer the last step's outcome, one of ${spec.outcomes.map((o) => `\`${o}\``).join(', ')}, followed by the state as \`name=value\`. It SHALL answer \`invalid\` when any step is malformed.`, + '', + '| State | Holds | Means |', + '| --- | --- | --- |', + ...spec.state.map((f) => `| \`${f.name}\` | ${f.kind === 'choice' ? accepts(f) : `whole number from ${f.min ?? 0} up to ${f.max}`} | ${f.means ?? ''} |`), + '', + '| Answer | Means |', + '| --- | --- |', + ...spec.outcomes.map((o) => `| \`${o}\` | ${spec.meanings?.[o] ?? ''} |`), + '| `invalid` | a step is malformed |', + '', + 'Verified: reading a session is tested, not proved.', + '', + ...(spec.limits ? ['## Out of scope', '', ...spec.limits.map((l) => `- ${l}`), ''] : []), + '## Examples', + '', + ...(spec.examples.length + ? spec.examples.flatMap((e) => e.steps.map((s, i) => `- \`${s}\` gives \`${e.answers[i]}\``).concat([''])) + : ['No example yet.', '']), + '## What is proved and what is tested', + '', + 'Lean proves that the start state is within bounds and that every action keeps it so, and each state property at the start and kept by every action from any state within bounds where all state properties hold. By induction over the steps of a session, each then holds in every reachable state. Each action property is proved for every such state. The proofs are about `after` and `reply`, the functions the WebAssembly guest runs, because both come from the same model.', + '', + `Reading sessions is tested, not proved: ${status.vectors ?? 'the'} acceptance vectors replay through the built guest, malformed and oversized sessions included.`, + '', + 'Nothing here says the rules are the right rules. That is the part only you can judge.', + '', + '## Files', + '', + '- `prism/spec.json` is this spec as data, the app\'s one input, in canonical JSON (RFC 8785). The model is rendered from it alone, so the same spec.json always gives the same model.', + `- \`src/${n.module}.lex.tex\` is the LexLean model generated from it, and \`src/${n.proofs}.lex.tex\` its theorems.`, + '', + ]; + return lines.join('\n'); +} + diff --git a/studio/shell/prism/render.mjs b/studio/shell/prism/render.mjs index b1e78843..cbe774af 100644 --- a/studio/shell/prism/render.mjs +++ b/studio/shell/prism/render.mjs @@ -9,21 +9,26 @@ * provable by one fixed proof form, with no proof written by hand. */ import { INVALID, MAX_DIGITS, describeConditions, encodeRequest, holds, judge, requestLimits, respond, sampleRequests } from './spec.mjs'; +import { STATEFUL_SCHEMA } from './stateful.mjs'; +import { renderStatefulModel, renderStatefulProofs, renderStatefulSpecDocument, statefulAcceptanceVectors, statefulNames } from './render-stateful.mjs'; -const LEAN_RESERVED = new Set([ +/** Whether a spec is a stateful one (`prism/spec/2`); every render below dispatches on it. */ +export const isStateful = (spec) => spec?.schema === STATEFUL_SCHEMA; + +export const LEAN_RESERVED = new Set([ 'let', 'if', 'match', 'fun', 'forall', 'nil', 'cons', 'first', 'second', 'not', 'apply', 'ctor', 'record', 'project', 'prim', 'ref', 'checked', 'then', 'else', 'with', 'true', 'false', 'at', 'by', 'do', 'end', 'from', 'have', 'in', 'mut', 'open', 'return', 'show', 'try', 'where', 'deriving', 'instance', 'structure', 'inductive', 'theorem', 'def', 'namespace', 'section', 'variable', 'axiom', 'example', 'abbrev', 'universe', 'local', 'private', 'protected', 'noncomputable', 'partial', 'unsafe', 'macro', 'syntax', 'calc', 'suffices', 'obtain', 'this', 'fields', 'value', 'request', 'text', 'number', 'code', 'type', 'prop', 'sort', ]); -const pascal = (word) => word.split(/[^a-z0-9]+/i).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(''); -const camel = (word) => { +export const pascal = (word) => word.split(/[^a-z0-9]+/i).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(''); +export const camel = (word) => { const p = pascal(word); return p[0].toLowerCase() + p.slice(1); }; -const hex = (text) => `0x${Buffer.from(typeof text === 'string' ? new TextEncoder().encode(text) : text).toString('hex')}`; +export const hex = (text) => `0x${Buffer.from(typeof text === 'string' ? new TextEncoder().encode(text) : text).toString('hex')}`; /** A LexLean string literal. Text is refused, never altered: validateSpec admits only printable ASCII without a quote or a backslash here. */ -const quote = (text) => { +export const quote = (text) => { const t = String(text); if (/[^ -~]|["\\]/.test(t)) throw new Error(`render refuses ${JSON.stringify(t)}: a LexLean string here carries printable ASCII without a quote or a backslash`); return `"${t}"`; @@ -31,6 +36,7 @@ const quote = (text) => { /** Every identifier the model uses, derived once so the model, the vectors and SPEC.md agree. */ export function names(spec) { + if (isStateful(spec)) return statefulNames(spec); const used = new Set(['Request', 'byteAt', 'digitsValue', 'parseDigits', 'parseNumber', 'sliceOf', 'fieldEnd', 'decodeField1', 'decodeField2', 'decodeField3', 'decodeField4', 'decodeField5', 'decodeField6', 'decodeField7', 'decodeField8', 'judge', 'encodeAnswer', 'dispatch', 'application']); const claim = (base) => { let name = base; @@ -58,7 +64,7 @@ export function names(spec) { } /** The application's artifact stem: letters, digits, spaces, hyphens, underscores and dots. */ -const stem = (title) => title.replace(/[^A-Za-z0-9 _.-]/g, '').replace(/^[^A-Za-z0-9]+/, '').replace(/[ .]+$/, '').slice(0, 128) || 'App'; +export const stem = (title) => title.replace(/[^A-Za-z0-9 _.-]/g, '').replace(/^[^A-Za-z0-9]+/, '').replace(/[ .]+$/, '').slice(0, 128) || 'App'; const condition = (spec, n, c, q = (x) => x) => { const field = n.fields[c.field]; @@ -77,7 +83,7 @@ const condition = (spec, n, c, q = (x) => x) => { } }; -const conjunction = (terms) => terms.reduce((acc, t) => (acc ? `(${acc} && ${t})` : t), ''); +export const conjunction = (terms) => terms.reduce((acc, t) => (acc ? `(${acc} && ${t})` : t), ''); /** * The bounds a decoded request satisfies, as conditions, so a property is @@ -94,7 +100,7 @@ const bounds = (spec) => ]); const ALL = '[Classical.choice, Quot.sound, propext]'; -const QP = '[Quot.sound, propext]'; +export const QP = '[Quot.sound, propext]'; /** * The declarations of the model, in order, each `{ name, text, axioms }`. @@ -312,7 +318,7 @@ function declarationValue(d) { export const declarationText = (d) => layout('', declarationValue(d), 0, '').join('\n'); -const moduleText = (name, imports, decls) => +export const moduleText = (name, imports, decls) => [ `\\begin{lexlean}{${name}}`, '\\useglossary{lexlean.std.bool@1.2.0}', @@ -327,19 +333,22 @@ const moduleText = (name, imports, decls) => '', ].join('\n'); -const withAxioms = (decls, axioms) => decls.map((d) => (Object.hasOwn(axioms, d.name) ? { ...d, axioms: axioms[d.name] } : d)); +export const withAxioms = (decls, axioms) => decls.map((d) => (Object.hasOwn(axioms, d.name) ? { ...d, axioms: axioms[d.name] } : d)); /** The app module: everything the guest runs. `axioms` overrides the expected set per declaration name. */ export function renderModel(spec, { axioms = {}, specAddress = null } = {}) { + if (isStateful(spec)) return renderStatefulModel(spec, { axioms, specAddress }); const n = names(spec); return moduleText(n.module, ['Foundation.Bytes', 'Foundation.View.Text.V1.Model'], withAxioms(declarations(spec, n, { specAddress }), axioms)); } /** * The seal: how an application says which spec it was built from. Its purpose, - * then the spec's UOR content address in `[prism/spec/1 blake3:]` — the - * same kappa the holo labels its own blobs with, so the spec is named the way - * everything else in a holo is named. + * then the spec's schema and UOR content address in `[prism/spec/1 blake3:]` + * (`prism/spec/2` for a stateful spec) — the same kappa the holo labels its own + * blobs with, so the spec is named the way everything else in a holo is named. + * The address covers the spec's canonical bytes, its schema among them, so the + * schema in the mark only says how to read the spec; the address decides. * * It is the model's `cargoDescription`, so it is inside the holo's model blob, * whose label is that blob's kappa and whose bytes the archive's footer @@ -349,11 +358,12 @@ export function renderModel(spec, { axioms = {}, specAddress = null } = {}) { * exactly this address, is where the spec itself belongs; that is the Rust * builder's to add. */ -export const SPEC_SEAL_MARK = /\[prism\/spec\/1 (blake3:[0-9a-f]{64})\]/; -export const describedBy = (spec, specAddress) => (specAddress ? `${spec.purpose || spec.title} [prism/spec/1 ${specAddress}]` : spec.purpose || spec.title); +export const SPEC_SEAL_MARK = /\[prism\/spec\/[12] (blake3:[0-9a-f]{64})\]/; +export const describedBy = (spec, specAddress) => (specAddress ? `${spec.purpose || spec.title} [${spec.schema ?? 'prism/spec/1'} ${specAddress}]` : spec.purpose || spec.title); /** The proofs module, or null when the spec states no property. */ export function renderProofs(spec, { axioms = {} } = {}) { + if (isStateful(spec)) return renderStatefulProofs(spec, { axioms }); const n = names(spec); if (spec.properties.length === 0) return null; return moduleText(n.proofs, [n.module], withAxioms(proofDeclarations(spec, n), axioms)); @@ -366,6 +376,7 @@ export function renderProofs(spec, { axioms = {} } = {}) { * long, as the text profile requires (SPEC.md section 3, PP2009). */ export function acceptanceVectors(spec) { + if (isStateful(spec)) return statefulAcceptanceVectors(spec); const enc = (s) => new TextEncoder().encode(s); const out = []; const seen = new Set(); @@ -428,19 +439,25 @@ export function acceptanceVectors(spec) { * same evaluator the vectors replay, so a scenario never claims what the rules * do not do. */ -function witness(spec, fits) { +function witnessAmong(spec, fits, candidates) { for (const e of spec.examples) { const parts = e.request.split(' '); if (parts.length !== spec.fields.length) continue; const request = Object.fromEntries(spec.fields.map((f, i) => [f.name, f.kind === 'number' && /^\d+$/.test(parts[i]) ? BigInt(parts[i]) : parts[i]])); if (respond(spec, new TextEncoder().encode(e.request)) !== INVALID && fits(request)) return { request, example: true }; } - let tried = 0; + for (const request of candidates()) if (fits(request)) return { request, example: false }; + return null; +} + +/** The candidate requests a witness is looked for among: the first 20,001 of the sample, in its order. */ +function firstRequests(spec) { + const out = []; for (const request of sampleRequests(spec)) { - if (fits(request)) return { request, example: false }; - if (++tried > 20000) break; + out.push(request); + if (out.length > 20000) break; } - return null; + return out; } /** @@ -451,11 +468,21 @@ function witness(spec, fits) { * why, then how, then what: the purpose and guarantees, the rules, the request. */ export function renderSpecDocument(spec, status = {}) { + if (isStateful(spec)) return renderStatefulSpecDocument(spec, status); const n = names(spec); const badge = (id) => ({ proved: 'proved by Lean for every request', failing: 'not proved: see the counterexample', tested: 'tested only' })[status.properties?.[id]] ?? 'to be proved by Lean for every request'; const because = (why) => (why ? `, because ${why.replace(/[.]$/, '')}` : ''); const plural = (k, one) => `${k} ${one}${k === 1 ? '' : 's'}`; - const decide = (request) => judge(spec, request); + // Every rule asks for a request it decides, among the same candidates and with the same judge: + // the candidates are listed once and each is judged once. Measured on 2026-11-16, asking afresh + // for each of 24 rules took 0.8 s of a 1.1 s call. The requests and their order are unchanged. + const judged = new WeakMap(); + const decide = (request) => { + if (!judged.has(request)) judged.set(request, judge(spec, request)); + return judged.get(request); + }; + let tried = null; + const witness = (_spec, fits) => witnessAmong(spec, fits, () => (tried ??= firstRequests(spec))); const scenario = (title, found, then) => { if (!found) return [`#### Scenario: ${title}`, '', `- **WHEN** a request meets the conditions above`, ...then(null)]; const text = encodeRequest(spec, found.request); diff --git a/studio/shell/prism/session.mjs b/studio/shell/prism/session.mjs index b0075eb1..3c73bcf9 100644 --- a/studio/shell/prism/session.mjs +++ b/studio/shell/prism/session.mjs @@ -11,6 +11,7 @@ import { counterexample, describeCondition, describeConditions, + isProposed, judge, decodeRequest, nameFromPurpose, @@ -23,7 +24,9 @@ import { titleFromName, unreachableRules, validateSpec, + checkText, } from './spec.mjs'; +import { STATEFUL_SCHEMA, statefulCounterexample } from './stateful.mjs'; export const STEPS = ['purpose', 'fields', 'outcomes', 'rules', 'properties', 'examples', 'review']; const NONE = /^\s*(none|no|nothing|skip|n\/a|-)\s*\.?\s*$/i; @@ -124,10 +127,16 @@ export function describeConditionPlain(c) { * what gets proved; when the whole spec is long, the rules are counted instead. */ export function summary(spec) { + if (spec?.schema === STATEFUL_SCHEMA) return statefulSummary(spec); if (!spec?.fields) return ''; const because = (why) => (why ? `, because ${why}` : ''); const purpose = [`${spec.title}: ${spec.purpose}`]; - const properties = spec.properties.map((p) => `${p.id}: ${p.kind} ${p.then} when ${describeConditions(p.when)}${because(p.why)} (to be proved)`); + // A guarantee Prism proposed comes first and says so: the user did not state it, and Lean will prove it once they agree. + const said = (p) => `${p.kind} ${p.then} when ${describeConditions(p.when)}`; + const properties = [ + ...spec.properties.filter(isProposed).map((p) => `${p.id}, proposed by Prism${/ from (REQ-\d+):/.exec(p.why) ? ` from ${/ from (REQ-\d+):/.exec(p.why)[1]}` : ''}: ${said(p)} (strike it if it is wrong; to be proved)`), + ...spec.properties.filter((p) => !isProposed(p)).map((p) => `${p.id}: ${said(p)}${because(p.why)} (to be proved)`), + ]; const rules = [...spec.rules.map((r) => `${r.id}: when ${describeConditions(r.when)}, ${r.then}${because(r.why)}`), `Otherwise: ${spec.otherwise}${because(spec.otherwiseWhy)}`]; const tail = [ `Request: ${spec.fields.map((f) => `${f.name} (${f.kind === 'choice' ? f.values.join('|') : `number${f.min !== undefined ? ` from ${f.min}` : ''}${f.max !== undefined ? ` up to ${f.max}` : ''}`}${f.means ? `; ${f.means}` : ''})`).join(', ')}`, @@ -138,8 +147,26 @@ export function summary(spec) { return [...purpose, ...properties, ...shown, ...tail].join('\n'); } -/** Answers that reproduce a whole spec, so a spec written as data joins the same flow. */ +/** A stateful spec on one screen: its properties first, then the state, the actions and the answers. */ +function statefulSummary(spec) { + const because = (why) => (why ? `, because ${why}` : ''); + const value = (f) => (f.kind === 'choice' ? f.values.join('|') : `number ${f.min ?? 0}..${f.max}`); + return [ + `${spec.title}: ${spec.purpose}`, + ...spec.properties.map((p) => `${p.id}: ${p.says.replace(/[.]$/, '')}${because(p.why)} (to be proved)`), + `State: ${spec.state.map((f) => `${f.name} (${value(f)}, starts ${f.start}${f.means ? `; ${f.means}` : ''})`).join(', ')}`, + ...spec.actions.map((a) => `Action ${[a.name, ...a.inputs.map((f) => `<${f.name}: ${f.kind === 'choice' ? f.values.join('|') : `number${f.min !== undefined ? ` from ${f.min}` : ''}${f.max !== undefined ? ` up to ${f.max}` : ''}`}>`)].join(' ')}: ${[...a.rules.map((r) => `${r.id} ${r.says.replace(/[.]$/, '')}`), `otherwise ${a.otherwise}${because(a.otherwiseWhy)}`].join('; ')}`), + `Answers: ${spec.outcomes.map((o) => (spec.meanings?.[o] ? `${o} (${spec.meanings[o]})` : o)).join(', ')}, or invalid; each with the state after it`, + ...(spec.limits ? [`Out of scope: ${spec.limits.map((l) => l.replace(/[.]$/, '')).join('; ')}`] : []), + ].join('\n'); +} + +/** + * Answers that reproduce a whole spec, so a spec written as data joins the same flow. + * A stateful spec (prism/spec/2) has no line answers: it is kept whole, as `stateful`. + */ export function answersFromSpec(input) { + if (input?.schema === STATEFUL_SCHEMA) return { stateful: validateSpec(input) }; const spec = validateSpec(input); const bound = (f) => (f.min !== undefined && f.max !== undefined ? ` ${f.min}..${f.max}` : f.min !== undefined ? ` at least ${f.min}` : f.max !== undefined ? ` at most ${f.max}` : ''); return { @@ -195,6 +222,7 @@ function withAbout(spec, about) { * `issue` explains why an answered step must be asked again. */ export function compile(answers) { + if (answers.stateful) return compileStateful(answers); const spec = {}; const notes = []; for (const step of STEPS) { @@ -207,6 +235,9 @@ export function compile(answers) { spec.name = answers.name ?? nameFromPurpose(text); spec.title = text.includes(':') && text.indexOf(':') < 40 ? text.slice(0, text.indexOf(':')).trim() : titleFromName(spec.name); spec.purpose = text.includes(':') && text.indexOf(':') < 40 ? text.slice(text.indexOf(':') + 1).trim() : text; + // Refused here, where it was said: left for the whole spec's check, a purpose too long or with a + // character text cannot carry was refused four questions later, at the rules. + checkText(spec.purpose, 'purpose', { ascii: true, max: 200 }); break; } case 'fields': @@ -226,6 +257,10 @@ export function compile(answers) { case 'properties': { spec.properties = NONE.test(String(raw)) ? [] : parseProperties(raw, spec.fields, spec.outcomes); if (spec.properties.length === 0) notes.push('No property is stated, so nothing about the rules will be proved; only the acceptance vectors will test them.'); + // A field nothing compares decides nothing, though every request must still give it. Measured on 2026-11-15: an agent listed a parcel's weight and wrote no rule for it, and nothing said so. + const compared = new Set([...spec.rules, ...spec.properties].flatMap((x) => x.when.flatMap((c) => [c.field, ...(c.value && typeof c.value === 'object' ? [c.value.field] : [])]))); + const idle = spec.fields.map((f) => f.name).filter((name) => !compared.has(name)); + if (idle.length) notes.push(`No rule or guarantee compares ${idle.join(', ')}, so ${idle.length === 1 ? 'it decides' : 'they decide'} nothing, though every request must still give ${idle.length === 1 ? 'it' : 'them'}. Add the rule that uses ${idle.length === 1 ? 'it' : 'them'}, or leave ${idle.length === 1 ? 'it' : 'them'} out.`); const v = validateSpec({ ...spec, examples: [] }); for (const p of v.properties) { const found = counterexample(v, p); @@ -267,6 +302,31 @@ export function compile(answers) { return { spec, step: 'ready', issue: null, notes }; } +/** + * A stateful spec, kept whole: it was read strictly when it was passed, so + * what is left is to look for a property the rules break, then the review. + */ +function compileStateful(answers) { + let spec; + try { + spec = validateSpec(answers.stateful); + } catch (error) { + if (!(error instanceof SpecError)) throw error; + return { spec: answers.stateful, step: 'review', issue: error.message, refusal: error.rule, notes: [] }; + } + const notes = spec.properties.length ? [] : ['No property is stated: Lean proves only that the state stays within its bounds; the acceptance vectors test the rest.']; + for (const p of spec.properties) { + const found = statefulCounterexample(spec, p); + if (found.steps !== null) { + const how = p.action ? `ends with ${p.action} answering ${found.outcome} (${found.rule ?? 'otherwise'})` : `reaches the state ${found.state}`; + return { spec, step: 'properties', issue: `${p.id} does not hold. The session \`${found.steps.join(';')}\` ${how}. Change a rule or restate the property, and pass the spec to prism_spec again.`, notes }; + } + } + if (answers.review === undefined || answers.review === null || String(answers.review).trim() === '') return { spec, step: 'review', issue: null, notes }; + if (!YES.test(String(answers.review))) return { spec, step: 'review', issue: 'Tell me what to change, and pass the changed spec to prism_spec.', notes }; + return { spec, step: 'ready', issue: null, notes }; +} + /** The parts of a spec a round trip must give back; ids and the sentences describing rules are derived. */ export const ROUND_TRIP_PARTS = Object.freeze(['name', 'title', 'purpose', 'fields', 'outcomes', 'rules', 'otherwise', 'properties', 'examples']); const part = (spec, key) => { @@ -285,6 +345,8 @@ const part = (spec, key) => { * are compared. */ export function roundTrip(input) { + // A stateful spec is its own answer: it is kept whole, so there is nothing to lose. + if (input?.schema === STATEFUL_SCHEMA) return null; const spec = validateSpec(input); const answers = { ...answersFromSpec(spec), review: 'yes' }; const back = compile(answers); @@ -297,6 +359,10 @@ export function roundTrip(input) { /** What the agent shows next: the question, any issue, notes, and progress. */ export function nextTurn(answers) { const { spec: bare, step, issue, refusal, notes } = compile(answers); + if (answers.stateful) { + const full = step === 'review' && issue && refusal ? null : bare; + return { step, ...(issue ? { issue } : {}), ...(notes.length ? { notes } : {}), ...question(step === 'properties' ? 'review' : step, full ?? {}), progress: step === 'ready' ? 'the stateful spec is approved' : 'the stateful spec is drafted', spec: full, refusal: refusal ?? null }; + } const spec = withAbout(bare, answers.about); const done = STEPS.indexOf(step) === -1 ? STEPS.length : STEPS.indexOf(step); const full = (() => { @@ -310,12 +376,15 @@ export function nextTurn(answers) { const unexplained = full.properties.filter((p) => !p.why).map((p) => p.id); if (unexplained.length) notes.push(`${unexplained.join(', ')} ${unexplained.length === 1 ? 'has' : 'have'} no reason. Lean proves ${unexplained.length === 1 ? 'it' : 'them'}, so say why each matters, or ask the user.`); } + const proposed = full && step === 'review' ? full.properties.filter(isProposed).map((p) => p.id) : []; + if (proposed.length) notes.push(`${proposed.join(', ')} ${proposed.length === 1 ? 'is a guarantee' : 'are guarantees'} Prism proposed from the rules, not something the user said. Show ${proposed.length === 1 ? 'it' : 'them'} first, as proposed, and let the user keep or strike each: Lean proves what stays.`); return { step, ...(issue ? { issue } : {}), ...(notes.length ? { notes } : {}), ...question(step, full ?? spec), ...(step === 'fields' || step === 'outcomes' ? { inferred: `The app is called ${spec.name}.` } : {}), + ...(proposed.length ? { proposed } : {}), progress: `${Math.min(done, 6)} of 6 answered`, spec: full, refusal: refusal ?? null, diff --git a/studio/shell/prism/spec-file.mjs b/studio/shell/prism/spec-file.mjs index 54196e0a..708086c1 100644 --- a/studio/shell/prism/spec-file.mjs +++ b/studio/shell/prism/spec-file.mjs @@ -16,6 +16,7 @@ import { createHash } from './sha256.mjs'; import { kappa } from '../prism-code/src/blake3.mjs'; import { SPEC_SCHEMA, SpecError, validateSpec } from './spec.mjs'; +import { STATEFUL_MEMBERS, STATEFUL_SCHEMA } from './stateful.mjs'; export const SPEC_FILE = 'spec.json'; @@ -39,10 +40,10 @@ const MEMBERS = Object.freeze({ const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v); -function closed(value, level, where) { +function closed(value, level, where, members = MEMBERS, schema = SPEC_SCHEMA) { if (!isObject(value)) refuse(`\`${where}\` must be an object.`, where, 'json.shape'); for (const key of Object.keys(value)) { - if (!MEMBERS[level].includes(key)) refuse(`\`${where}.${key}\` is not a member of ${level === 'spec' ? SPEC_SCHEMA : `a ${level}`}; the members are ${MEMBERS[level].join(', ')}.`, `${where}.${key}`, 'json.member'); + if (!members[level].includes(key)) refuse(`\`${where}.${key}\` is not a member of ${level === 'spec' ? schema : `a ${level}`}; the members are ${members[level].join(', ')}.`, `${where}.${key}`, 'json.member'); } } @@ -54,6 +55,8 @@ const list = (value, where) => { /** Refuse any member `prism/spec/1` does not define, naming its path. */ export function checkMembers(spec) { + if (isObject(spec) && spec.schema !== undefined && spec.schema !== SPEC_SCHEMA && spec.schema !== STATEFUL_SCHEMA) refuse(`\`$.schema\` is ${JSON.stringify(spec.schema)}; a spec is ${SPEC_SCHEMA}, or ${STATEFUL_SCHEMA} for an app that keeps state.`, '$.schema', 'spec.schema'); + if (isObject(spec) && spec.schema === STATEFUL_SCHEMA) return checkStatefulMembers(spec); closed(spec, 'spec', '$'); list(spec.fields, '$.fields').forEach((f, i) => closed(f, 'field', `$.fields[${i}]`)); const conditions = (conds, where) => @@ -73,6 +76,33 @@ export function checkMembers(spec) { if (spec.meanings !== undefined && !isObject(spec.meanings)) refuse('`$.meanings` must be an object.', '$.meanings', 'json.shape'); } +/** Refuse any member `prism/spec/2` does not define, naming its path. */ +function checkStatefulMembers(spec) { + const at = (value, level, where) => closed(value, level, where, STATEFUL_MEMBERS, STATEFUL_SCHEMA); + const items = (conds, where, level) => + list(conds, where).forEach((c, j) => { + at(c, level, `${where}[${j}]`); + if (isObject(c.value)) at(c.value, 'operand', `${where}[${j}].value`); + }); + at(spec, 'spec', '$'); + list(spec.state, '$.state').forEach((f, i) => at(f, 'value', `$.state[${i}]`)); + list(spec.actions, '$.actions').forEach((a, i) => { + at(a, 'action', `$.actions[${i}]`); + list(a.inputs, `$.actions[${i}].inputs`).forEach((f, j) => at(f, 'input', `$.actions[${i}].inputs[${j}]`)); + list(a.rules, `$.actions[${i}].rules`).forEach((r, j) => { + at(r, 'rule', `$.actions[${i}].rules[${j}]`); + items(r.when, `$.actions[${i}].rules[${j}].when`, 'condition'); + items(r.change, `$.actions[${i}].rules[${j}].change`, 'change'); + }); + }); + list(spec.properties, '$.properties').forEach((p, i) => { + at(p, 'property', `$.properties[${i}]`); + items(p.when, `$.properties[${i}].when`, 'condition'); + }); + list(spec.examples, '$.examples').forEach((e, i) => at(e, 'example', `$.examples[${i}]`)); + if (spec.meanings !== undefined && !isObject(spec.meanings)) refuse('`$.meanings` must be an object.', '$.meanings', 'json.shape'); +} + /** * JSON text to a value, strictly: a duplicate key, a number that is not a whole * number within plus or minus 2^53, or text that is not JSON is refused. diff --git a/studio/shell/prism/spec-schema.mjs b/studio/shell/prism/spec-schema.mjs new file mode 100644 index 00000000..a51ea40a --- /dev/null +++ b/studio/shell/prism/spec-schema.mjs @@ -0,0 +1,66 @@ +/** + * `prism/spec/1` as JSON Schema, for a caller that can hold a model's answer + * to a schema (constrained decoding, a structured-output API, a tool input). + * + * `DRAFT_JSON_SCHEMA` is what a model writes: a title, the fields, the rules + * and the default answer, and a guarantee only when the user stated one. + * `completeSpec` (complete.mjs) derives the rest. Whatever satisfies it is a + * draft `completeSpec` reads; it is deliberately narrower than every draft + * Prism accepts, so a constrained model has nothing else to write. + * + * `SPEC_JSON_SCHEMA` is the whole spec, every member `spec.json` may hold. + * + * A schema cannot say everything: that a rule names a field that exists, that + * a choice is one of its field's values, that `min` is not above `max`. The + * checker (`checkSpec`) still decides those. + */ +const WORD = { type: 'string', pattern: '^[a-z][a-z0-9-]{0,31}$' }; +const WHOLE = { type: 'integer', minimum: 0 }; +const TEXT = { type: 'string' }; + +const CONDITION = { + type: 'object', + properties: { + field: WORD, + op: { enum: ['is', 'is not', '<', '<=', '>', '>=', '=', '!='] }, + value: { anyOf: [WHOLE, WORD, { type: 'object', properties: { field: WORD }, required: ['field'], additionalProperties: false }] }, + }, + required: ['field', 'op', 'value'], + additionalProperties: false, +}; +const WHEN = { type: 'array', minItems: 1, items: CONDITION }; + +const closed = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false }); + +const field = (extra = {}) => closed({ name: WORD, kind: { enum: ['number', 'choice'] }, values: { type: 'array', minItems: 2, maxItems: 32, items: WORD }, min: WHOLE, max: WHOLE, ...extra }, ['name', 'kind']); +const fields = (extra) => ({ type: 'array', minItems: 1, maxItems: 8, items: field(extra) }); +const rules = (extra = {}) => ({ type: 'array', minItems: 1, maxItems: 24, items: closed({ when: WHEN, then: WORD, ...extra }, ['when', 'then']) }); +const properties = (extra = {}) => ({ type: 'array', items: closed({ kind: { enum: ['never', 'always'] }, when: WHEN, then: WORD, ...extra }, ['kind', 'when', 'then']) }); + +/** The draft form: what a model writes. Number bounds are whole and not negative; no member beyond these is allowed. */ +export const DRAFT_JSON_SCHEMA = Object.freeze( + closed({ title: { type: 'string', maxLength: 64 }, fields: fields(), rules: rules(), otherwise: WORD, properties: properties() }, ['title', 'fields', 'rules', 'otherwise']), +); + +/** The whole spec: every member `prism/spec.json` may hold. */ +export const SPEC_JSON_SCHEMA = Object.freeze( + closed( + { + schema: { const: 'prism/spec/1' }, + name: { type: 'string', pattern: '^[a-z][a-z0-9-]{0,62}$' }, + title: { type: 'string', maxLength: 64 }, + purpose: { type: 'string', minLength: 1, maxLength: 200 }, + actors: { type: 'array', items: TEXT }, + limits: { type: 'array', items: TEXT }, + fields: fields({ means: TEXT }), + outcomes: { type: 'array', minItems: 2, items: WORD }, + meanings: { type: 'object', additionalProperties: TEXT }, + rules: rules({ id: TEXT, says: TEXT, why: TEXT }), + otherwise: WORD, + otherwiseWhy: TEXT, + properties: properties({ id: TEXT, says: TEXT, why: TEXT }), + examples: { type: 'array', items: closed({ request: TEXT, response: WORD }, ['request', 'response']) }, + }, + ['purpose', 'fields', 'outcomes', 'rules', 'otherwise'], + ), +); diff --git a/studio/shell/prism/spec.mjs b/studio/shell/prism/spec.mjs index 4586e89d..67f50e13 100644 --- a/studio/shell/prism/spec.mjs +++ b/studio/shell/prism/spec.mjs @@ -13,12 +13,18 @@ * and it mirrors the model's semantics exactly (see render.mjs). */ +import { STATEFUL_SCHEMA, validateStatefulSpec } from './stateful.mjs'; + export const SPEC_SCHEMA = 'prism/spec/1'; export const INVALID = 'invalid'; /** A number is at most 18 decimal digits, so every value fits the guest's 64-bit arithmetic with room to spare. */ export const MAX_DIGITS = 18; export const NAT_MAX = 10n ** 18n - 1n; +/** How the reason of a guarantee Prism proposed starts (complete.mjs). A surface shows a guarantee whose `why` starts so as proposed. */ +export const PROPOSED = 'Proposed by Prism'; +export const isProposed = (property) => typeof property?.why === 'string' && property.why.startsWith(PROPOSED); + const WORD = /^[a-z][a-z0-9-]{0,31}$/; const NAME = /^[a-z][a-z0-9-]{0,62}$/; const OPS = ['<', '<=', '>', '>=', '=', '!=']; @@ -216,8 +222,10 @@ const withWhy = (item, why, where) => (prose(why, where) ? { ...item, why } : it /** Validate a whole spec; return it normalized. Throws `SpecError` naming the first problem. */ export function validateSpec(input) { + // A stateful spec (prism/spec/2, stateful.mjs) is read by its own rules. + if (input?.schema === STATEFUL_SCHEMA) return validateStatefulSpec(input); const spec = structuredClone(input ?? {}); - if (spec.schema !== undefined && spec.schema !== SPEC_SCHEMA) refuse(`schema must be ${SPEC_SCHEMA}`, 'schema', 'spec.schema'); + if (spec.schema !== undefined && spec.schema !== SPEC_SCHEMA) refuse(`schema must be ${SPEC_SCHEMA}, or ${STATEFUL_SCHEMA} for an app that keeps state`, 'schema', 'spec.schema'); spec.schema = SPEC_SCHEMA; if (!spec.name) spec.name = nameFromPurpose(spec.purpose); if (!NAME.test(spec.name)) refuse('name must be lower case letters, digits and hyphens, starting with a letter', 'name', 'spec.name'); @@ -271,12 +279,18 @@ export function validateSpec(input) { const f = fields.find((x) => x.name === c.field); if (!f) refuse(`\`${c.field}\` is not a field.`, where, 'condition.unknown-field'); if (f.kind === 'choice') { - if (!['is', 'is not'].includes(c.op) || !f.values.includes(c.value)) refuse(`\`${c.field} ${c.op} ${c.value}\` does not name a choice of ${c.field}.`, where, 'choice.value'); + // Measured with Qwen3 30B on 2026-11-15: `=` on a choice was refused as a value that "does not name a choice", which it did. + if (!['is', 'is not'].includes(c.op)) refuse(`\`${c.field}\` is a choice; compare it with "is" or "is not", not \`${c.op}\`.`, where, 'choice.comparison'); + if (!f.values.includes(c.value)) refuse(`\`${c.value}\` is not a choice of \`${c.field}\`; the choices are ${f.values.join(', ')}.`, where, 'choice.value'); } else { - if (!OPS.includes(c.op)) refuse(`\`${c.op}\` is not a comparison.`, where, 'condition.comparison'); + if (!OPS.includes(c.op)) refuse(`\`${c.op}\` is not a comparison for the number \`${c.field}\`; use one of ${OPS.join(', ')}.`, where, 'condition.comparison'); if (typeof c.value === 'number') { if (!(Number.isSafeInteger(c.value) && c.value >= 0)) refuse('Compare numbers with whole numbers.', where, 'condition.number'); - } else if (!(c.value && fields.some((x) => x.name === c.value.field && x.kind === 'number'))) refuse(`\`${JSON.stringify(c.value)}\` is not a number field.`, where, 'condition.operand'); + } else if (!(c.value && fields.some((x) => x.name === c.value.field && x.kind === 'number'))) { + // Measured with Qwen3 30B (#666): the other field written as a bare word, six runs of thirty, and the bare refusal was not repaired once. + const meant = typeof c.value === 'string' && fields.some((x) => x.name === c.value && x.kind === 'number'); + refuse(meant ? `\`${c.field} ${c.op} ${JSON.stringify(c.value)}\` compares with the text ${JSON.stringify(c.value)}; to compare with the field \`${c.value}\`, write the value as {"field": ${JSON.stringify(c.value)}}.` : `\`${JSON.stringify(c.value)}\` is not a number field.`, where, 'condition.operand'); + } } } }; @@ -403,8 +417,14 @@ function candidates(spec) { }); } +/** How many requests the candidate values make. A search that tried this many tried every one of them. */ +export const sampleSize = (spec) => candidates(spec).reduce((n, list) => n * list.length, 1); + +/** How many candidate requests a search tries before it stops and claims nothing. */ +const SAMPLE_REQUESTS = 200000; + /** Every decoded request over the candidate values, up to `limit`. */ -export function* sampleRequests(spec, limit = 200000) { +export function* sampleRequests(spec, limit = SAMPLE_REQUESTS) { const lists = candidates(spec); const index = lists.map(() => 0); let count = 0; @@ -440,6 +460,9 @@ export function unreachableRules(spec) { // values is never reached though it decides plenty. A rule is called unreachable // only when every combination was tried; otherwise nothing is claimed. const total = candidates(spec).reduce((n, list) => n * list.length, 1); + // More combinations than the sample tries: nothing can be claimed, so nothing is tried. + // Measured on 2026-11-16: the pass took 250 ms for the largest draft and ran four times a call. + if (total > SAMPLE_REQUESTS) return []; const hit = new Set(); let tried = 0; for (const request of sampleRequests(spec)) { diff --git a/studio/shell/prism/stateful.mjs b/studio/shell/prism/stateful.mjs new file mode 100644 index 00000000..8352ea86 --- /dev/null +++ b/studio/shell/prism/stateful.mjs @@ -0,0 +1,493 @@ +/** + * The stateful Prism spec (`prism/spec/2`): an app that keeps state between + * the steps of a session. One spec renders to one LexLean model + * (render-stateful.mjs), whose theorems Lean proves over every reachable + * state and whose acceptance vectors the guest replays. + * + * The state is a few named values, each a bounded number or a choice, with a + * start value. An action is a word and its inputs, as a spec/1 request is a + * line of fields. Each action has ordered rules: the first whose conditions + * hold and whose changes keep every number within its bounds decides the + * answer and changes the state; when none does, the action answers its + * `otherwise` and changes nothing. A malformed step is `invalid`. + * + * Properties are what Lean proves: + * - a state property (`always` or `never` with `when` over the state) holds + * in every reachable state: Lean proves it at the start and kept by every + * action, assuming every state property and the bounds; + * - an action property (`never` or `always`, an `action`, `when` over the + * state and its inputs, `then` an answer) holds in every state where the + * state properties and bounds hold, so in every reachable one. + * + * Examples are acceptance sessions: steps and the answer each step gives. + * + * This module is pure. Its top level reads nothing from spec.mjs, which + * imports it, so either may be loaded first. + */ +import { INVALID, MAX_DIGITS, NAT_MAX, SpecError, checkText, nameFromPurpose, parseNumber, titleFromName } from './spec.mjs'; + +export const STATEFUL_SCHEMA = 'prism/spec/2'; +/** A session is one request of at most this many bytes: its steps separated by `;`. */ +export const SESSION_BYTES = 1024; + +const WORD = /^[a-z][a-z0-9-]{0,31}$/; +const NAME = /^[a-z][a-z0-9-]{0,62}$/; +const OPS = ['<', '<=', '>', '>=', '=', '!=']; +const CHANGE_OPS = ['set', 'add', 'subtract']; + +/** Every rule a stateful spec can be refused by, beyond the rules it shares with prism/spec/1 (spec.mjs REFUSALS). */ +export const STATEFUL_REFUSALS = Object.freeze([ + 'action.duplicate', 'action.name', 'actions.none', 'actions.too-many', + 'change.bound', 'change.duplicate', 'change.op', 'change.operand', 'change.unknown-field', + 'example.answer', 'example.disagrees', 'example.step', + 'input.clash', 'inputs.too-many', + 'property.action', 'properties.too-many', + 'state.bound', 'state.none', 'state.start', 'state.too-many', +]); + +/** The members each level of a stateful spec may hold; spec-file.mjs refuses anything else. */ +export const STATEFUL_MEMBERS = Object.freeze({ + spec: ['schema', 'name', 'title', 'purpose', 'actors', 'limits', 'state', 'outcomes', 'meanings', 'actions', 'properties', 'examples'], + value: ['name', 'kind', 'values', 'min', 'max', 'start', 'means'], + input: ['name', 'kind', 'values', 'min', 'max', 'means'], + action: ['name', 'means', 'inputs', 'rules', 'otherwise', 'otherwiseWhy'], + rule: ['id', 'when', 'then', 'change', 'says', 'why'], + property: ['id', 'kind', 'action', 'when', 'then', 'says', 'why'], + condition: ['field', 'op', 'value'], + change: ['field', 'op', 'value'], + operand: ['field'], + example: ['steps', 'answers'], +}); + +const refuse = (message, where, rule) => { + throw new SpecError(message, where, rule); +}; +const prose = (text, where) => (text === undefined || text === null || text === '' ? '' : checkText(text, where)); +const withWhy = (item, why, where) => (prose(why, where) ? { ...item, why } : item); +const isWholeNumber = (n) => Number.isSafeInteger(n) && n >= 0 && n <= Number(NAT_MAX); + +/** A number or choice, as a state value (`state: true`, with a start) or as an action's input. */ +function checkValue(f, where, { state }) { + const out = { name: f.name, kind: f.kind }; + if (!WORD.test(f.name ?? '')) refuse(`Name \`${f.name}\` must be a lower-case word.`, where, 'field.name'); + if (f.kind === 'choice') { + if (!Array.isArray(f.values) || f.values.length < 2) refuse(`\`${f.name}\` needs at least two choices.`, where, 'choice.too-few'); + if (f.values.length > 32) refuse(`\`${f.name}\` has more than 32 choices.`, where, 'choice.too-many'); + if (new Set(f.values).size !== f.values.length) refuse(`\`${f.name}\` repeats a choice.`, where, 'choice.duplicate'); + for (const v of f.values) if (!WORD.test(v)) refuse(`Choice \`${v}\` must be a lower-case word without spaces.`, where, 'choice.word'); + out.values = [...f.values]; + if (f.min !== undefined || f.max !== undefined) refuse(`\`${f.name}\` is a choice; it has no min or max.`, where, 'number.bound'); + if (state) { + const start = f.start ?? f.values[0]; + if (!f.values.includes(start)) refuse(`\`${f.name}\` starts at \`${start}\`, which is not one of its choices.`, where, 'state.start'); + out.start = start; + } + } else if (f.kind === 'number') { + if (f.values !== undefined) refuse(`\`${f.name}\` is a number; it has no choices.`, where, 'field.kind'); + for (const b of ['min', 'max']) if (f[b] !== undefined && !isWholeNumber(f[b])) refuse(`\`${b}\` of \`${f.name}\` must be a whole number of at most ${MAX_DIGITS} digits.`, where, 'number.bound'); + if (state && f.max === undefined) refuse(`State \`${f.name}\` needs a \`max\`: state is bounded, so Lean can prove every action keeps it in bounds.`, where, 'state.bound'); + if (f.min !== undefined && f.max !== undefined && f.min > f.max) refuse(`\`${f.name}\` has min above max.`, where, 'number.bound-order'); + if (f.min !== undefined) out.min = f.min; + if (f.max !== undefined) out.max = f.max; + if (state) { + const start = f.start ?? f.min ?? 0; + if (!isWholeNumber(start) || start < (f.min ?? 0) || start > f.max) refuse(`\`${f.name}\` starts at ${JSON.stringify(start)}, outside ${f.min ?? 0}..${f.max}.`, where, 'state.start'); + out.start = start; + } + } else refuse(`\`${f.name}\` must be a \`number\` or a \`choice\`.`, where, 'field.kind'); + if (!state && f.start !== undefined) refuse(`Input \`${f.name}\` has no start; only state does.`, where, 'state.start'); + const means = prose(f.means, `${where}.means`); + if (means) out.means = means; + return out; +} + +/** Conditions over `fields` (the state, and an action's inputs where it has them). Empty is allowed where `empty`. */ +function checkConditions(conds, fields, where, { empty = false } = {}) { + if (conds === undefined && empty) return []; + if (!Array.isArray(conds) || (conds.length === 0 && !empty)) refuse(`Each ${where} needs at least one condition.`, where, 'condition.none'); + return conds.map((c) => { + const f = fields.find((x) => x.name === c.field); + if (!f) refuse(`\`${c.field}\` is neither a state value nor an input here; these are ${fields.map((x) => x.name).join(', ')}.`, where, 'condition.unknown-field'); + if (f.kind === 'choice') { + if (!['is', 'is not'].includes(c.op) || !f.values.includes(c.value)) refuse(`\`${c.field} ${c.op} ${JSON.stringify(c.value)}\` does not name a choice of ${c.field}.`, where, 'choice.value'); + return { field: c.field, op: c.op, value: c.value }; + } + if (!OPS.includes(c.op)) refuse(`\`${c.op}\` is not a comparison of numbers.`, where, 'condition.comparison'); + if (typeof c.value === 'number') { + if (!isWholeNumber(c.value)) refuse('Compare numbers with whole numbers.', where, 'condition.number'); + return { field: c.field, op: c.op, value: c.value }; + } + if (!(c.value && fields.some((x) => x.name === c.value.field && x.kind === 'number'))) refuse(`\`${JSON.stringify(c.value)}\` is not a whole number or a number here.`, where, 'condition.operand'); + return { field: c.field, op: c.op, value: { field: c.value.field } }; + }); +} + +/** The changes of a rule: each state value at most once, each read from the state before the step. */ +function checkChanges(changes, state, fields, where) { + if (changes === undefined) return []; + if (!Array.isArray(changes)) refuse('`change` is a list of changes to the state.', where, 'change.op'); + const seen = new Set(); + return changes.map((c) => { + const f = state.find((x) => x.name === c.field); + if (!f) refuse(`\`${c.field}\` is not a state value; only state changes.`, where, 'change.unknown-field'); + if (seen.has(c.field)) refuse(`\`${c.field}\` changes twice in one rule.`, where, 'change.duplicate'); + seen.add(c.field); + if (!CHANGE_OPS.includes(c.op)) refuse(`A change is \`set\`, \`add\` or \`subtract\`; got \`${c.op}\`.`, where, 'change.op'); + if (f.kind === 'choice') { + if (c.op !== 'set') refuse(`\`${c.field}\` is a choice; it can only be \`set\`.`, where, 'change.op'); + if (!f.values.includes(c.value)) refuse(`\`${JSON.stringify(c.value)}\` is not a choice of ${c.field}.`, where, 'choice.value'); + return { field: c.field, op: 'set', value: c.value }; + } + if (typeof c.value === 'number') { + if (!isWholeNumber(c.value)) refuse('Change numbers by whole numbers.', where, 'condition.number'); + if (c.op === 'set' && (c.value < (f.min ?? 0) || c.value > f.max)) refuse(`Setting \`${c.field}\` to ${c.value} leaves ${f.min ?? 0}..${f.max}.`, where, 'change.bound'); + return { field: c.field, op: c.op, value: c.value }; + } + if (!(c.value && fields.some((x) => x.name === c.value.field && x.kind === 'number'))) refuse(`\`${JSON.stringify(c.value)}\` is not a whole number or a number here.`, where, 'change.operand'); + return { field: c.field, op: c.op, value: { field: c.value.field } }; + }); +} + +/** Validate a whole stateful spec; return it normalized. Throws `SpecError` naming the first problem. */ +export function validateStatefulSpec(input) { + const raw = structuredClone(input ?? {}); + if (raw.schema !== STATEFUL_SCHEMA) refuse(`schema must be ${STATEFUL_SCHEMA}`, 'schema', 'spec.schema'); + const spec = { schema: STATEFUL_SCHEMA }; + spec.name = raw.name || nameFromPurpose(raw.purpose); + if (!NAME.test(spec.name)) refuse('name must be lower case letters, digits and hyphens, starting with a letter', 'name', 'spec.name'); + spec.title = raw.title === undefined ? titleFromName(spec.name) : checkText(raw.title, 'title', { ascii: true, max: 64 }); + if (!spec.title) refuse('`title` is empty; leave it out to take it from the name.', 'title', 'text.length'); + if (raw.purpose === undefined || raw.purpose === null || raw.purpose === '') refuse('Say in one sentence what the app keeps and does.', 'purpose', 'spec.purpose'); + spec.purpose = checkText(raw.purpose, 'purpose', { ascii: true, max: 200 }); + const actors = (raw.actors ?? []).map((a, i) => checkText(a, `actors[${i}]`, { max: 64 })); + if (actors.length) spec.actors = actors; + if (raw.limits !== undefined && !Array.isArray(raw.limits)) refuse('`limits` is a list of what the app does not do.', 'limits', 'spec.limits'); + const limits = (raw.limits ?? []).filter((l, i) => prose(l, `limits[${i}]`)); + if (limits.length) spec.limits = limits; + + if (!Array.isArray(raw.state) || raw.state.length === 0) refuse('Name at least one state value the app keeps, such as `{"name": "count", "kind": "number", "max": 100}`.', 'state', 'state.none'); + if (raw.state.length > 8) refuse('An app keeps at most eight state values.', 'state', 'state.too-many'); + spec.state = raw.state.map((f, i) => checkValue(f, `state[${i}]`, { state: true })); + if (new Set(spec.state.map((f) => f.name)).size !== spec.state.length) refuse('A state value is named twice.', 'state', 'field.duplicate'); + + const outcomes = raw.outcomes ?? []; + if (!Array.isArray(outcomes) || outcomes.length < 2) refuse('Name at least two answers.', 'outcomes', 'outcomes.too-few'); + if (new Set(outcomes).size !== outcomes.length) refuse('An answer is named twice.', 'outcomes', 'outcomes.duplicate'); + for (const o of outcomes) { + if (!WORD.test(o)) refuse(`Answer \`${o}\` must be a lower-case word.`, 'outcomes', 'outcomes.word'); + if (o === INVALID) refuse('`invalid` is reserved for malformed steps; pick another word.', 'outcomes', 'outcomes.reserved'); + } + spec.outcomes = [...outcomes]; + if (raw.meanings !== undefined) { + if (typeof raw.meanings !== 'object' || raw.meanings === null || Array.isArray(raw.meanings)) refuse('`meanings` maps each answer to what it means.', 'outcomes', 'meanings.shape'); + for (const key of Object.keys(raw.meanings)) if (!outcomes.includes(key)) refuse(`\`meanings\` names \`${key}\`, which is not an answer.`, 'outcomes', 'meanings.unknown'); + const meanings = Object.fromEntries(outcomes.filter((o) => prose(raw.meanings[o], `meanings.${o}`)).map((o) => [o, raw.meanings[o]])); + if (Object.keys(meanings).length) spec.meanings = meanings; + } + + if (!Array.isArray(raw.actions) || raw.actions.length === 0) refuse('Name at least one action a user can take.', 'actions', 'actions.none'); + if (raw.actions.length > 8) refuse('An app has at most eight actions.', 'actions', 'actions.too-many'); + let ruleCount = 0; + spec.actions = raw.actions.map((a, ai) => { + const where = `actions[${ai}]`; + if (!WORD.test(a.name ?? '')) refuse(`Action name \`${a.name}\` must be a lower-case word.`, where, 'action.name'); + const inputs = a.inputs ?? []; + if (!Array.isArray(inputs) || inputs.length > 4) refuse(`Action \`${a.name}\` takes at most four inputs.`, where, 'inputs.too-many'); + const ins = inputs.map((f, i) => checkValue(f, `${where}.inputs[${i}]`, { state: false })); + for (const f of ins) if (spec.state.some((s) => s.name === f.name)) refuse(`Input \`${f.name}\` of \`${a.name}\` has the name of a state value.`, where, 'input.clash'); + if (new Set(ins.map((f) => f.name)).size !== ins.length) refuse(`Action \`${a.name}\` names an input twice.`, where, 'field.duplicate'); + const fields = [...spec.state, ...ins]; + if (!Array.isArray(a.rules)) refuse(`Action \`${a.name}\` needs \`rules\`, possibly empty, and an \`otherwise\`.`, where, 'rules.format'); + if (a.rules.length > 12) refuse(`Action \`${a.name}\` has more than 12 rules.`, where, 'rules.too-many'); + const rules = a.rules.map((r, ri) => { + const rw = `${where}.rules[${ri}]`; + if (!outcomes.includes(r.then)) refuse(`Rule ${ri + 1} of \`${a.name}\` answers \`${r.then}\`, which is not an answer.`, rw, 'outcome.unknown'); + const when = checkConditions(r.when, fields, rw, { empty: true }); + const change = checkChanges(r.change, spec.state, fields, rw); + ruleCount++; + const id = r.id ?? `REQ-${String(ruleCount).padStart(3, '0')}`; + if (typeof id !== 'string' || !/^[A-Z][A-Z0-9-]{0,31}$/.test(id)) refuse(`Rule id ${JSON.stringify(id)} must be upper-case letters, digits and hyphens, such as REQ-001.`, rw, 'rules.format'); + if (r.says !== undefined) checkText(r.says, `${rw}.says`); + return withWhy({ id, when, then: r.then, change, says: r.says ?? describeStatefulRule(a.name, { when, then: r.then, change }) }, r.why, `${rw}.why`); + }); + if (!outcomes.includes(a.otherwise)) refuse(`Say which answer \`${a.name}\` gives when no rule applies, as \`otherwise\`.`, where, 'rules.otherwise'); + const action = { name: a.name, inputs: ins, rules, otherwise: a.otherwise }; + const means = prose(a.means, `${where}.means`); + if (means) action.means = means; + const why = prose(a.otherwiseWhy, `${where}.otherwiseWhy`); + if (why) action.otherwiseWhy = why; + return action; + }); + const actionNames = spec.actions.map((a) => a.name); + if (new Set(actionNames).size !== actionNames.length) refuse('An action is named twice.', 'actions', 'action.duplicate'); + const ruleIds = spec.actions.flatMap((a) => a.rules.map((r) => r.id)); + if (new Set(ruleIds).size !== ruleIds.length) refuse('A rule id is used twice.', 'actions', 'rules.format'); + + const props = raw.properties ?? []; + if (!Array.isArray(props)) refuse('`properties` is a list.', 'properties', 'properties.format'); + if (props.length > 16) refuse('Keep to at most 16 properties.', 'properties', 'properties.too-many'); + spec.properties = props.map((p, i) => { + const where = `properties[${i}]`; + if (!['never', 'always'].includes(p.kind)) refuse('A property is `never` or `always`.', where, 'properties.kind'); + const id = p.id ?? `INV-${String(i + 1).padStart(3, '0')}`; + if (typeof id !== 'string' || !/^[A-Z][A-Z0-9-]{0,31}$/.test(id)) refuse(`Property id ${JSON.stringify(id)} must be upper-case letters, digits and hyphens, such as INV-001.`, where, 'properties.format'); + let out; + if (p.action === undefined) { + if (p.then !== undefined) refuse('A property with `then` names the `action` that answers it.', where, 'property.action'); + out = { id, kind: p.kind, when: checkConditions(p.when, spec.state, where) }; + } else { + const action = spec.actions.find((a) => a.name === p.action); + if (!action) refuse(`\`${p.action}\` is not an action.`, where, 'property.action'); + if (!outcomes.includes(p.then)) refuse(`Property ${i + 1} names \`${p.then}\`, which is not an answer.`, where, 'outcome.unknown'); + const when = checkConditions(p.when, [...spec.state, ...action.inputs], where, { empty: true }); + out = { id, kind: p.kind, action: p.action, when, then: p.then }; + } + if (p.says !== undefined) checkText(p.says, `${where}.says`); + return withWhy({ ...out, says: p.says ?? describeStatefulProperty(out) }, p.why, `${where}.why`); + }); + if (new Set(spec.properties.map((p) => p.id)).size !== spec.properties.length) refuse('A property id is used twice.', 'properties', 'properties.format'); + + const examples = raw.examples ?? []; + if (!Array.isArray(examples)) refuse('`examples` is a list of sessions.', 'examples', 'examples.format'); + spec.examples = examples.map((e, i) => { + const where = `examples[${i}]`; + if (!Array.isArray(e.steps) || e.steps.length === 0 || !Array.isArray(e.answers) || e.answers.length !== e.steps.length) refuse('An example is `steps` and as many `answers`, one per step.', where, 'examples.format'); + for (const s of e.steps) if (typeof s !== 'string' || s.includes(';')) refuse(`Step ${JSON.stringify(s)} must be one action and its inputs, separated by single spaces, without \`;\`.`, where, 'example.step'); + for (const a of e.answers) if (a !== INVALID && !outcomes.includes(a)) refuse(`Example ${i + 1} expects \`${a}\`, which is not an answer.`, where, 'example.answer'); + return { steps: [...e.steps], answers: [...e.answers] }; + }); + // An example is an acceptance session: it must be what the rules do, or the spec says two things. + for (const [i, e] of spec.examples.entries()) { + const got = runSession(spec, e.steps); + const at = got.findIndex((g, j) => g.outcome !== e.answers[j]); + if (at >= 0) { + const g = got[at]; + refuse(`Example ${i + 1} expects step ${at + 1} (\`${e.steps[at]}\`) to answer ${e.answers[at]}, but it answers ${g.outcome}${g.rule ? `, decided by ${g.rule}` : g.outcome === INVALID ? ', because the step is malformed' : ', by otherwise'}. Fix the example, or change the rules.`, `examples[${i}]`, 'example.disagrees'); + } + } + return spec; +} + +const OP_WORDS = { '<': 'is below', '<=': 'is at most', '>': 'is above', '>=': 'is at least', '=': 'equals', '!=': 'differs from', is: 'is', 'is not': 'is not' }; +const describeCondition = (c) => `${c.field} ${OP_WORDS[c.op]} ${typeof c.value === 'object' ? c.value.field : c.value}`; +export const describeStatefulConditions = (conds) => (conds.length ? conds.map(describeCondition).join(' and ') : 'always'); +const describeChange = (c) => { + const v = typeof c.value === 'object' ? c.value.field : c.value; + return c.op === 'set' ? `${c.field} becomes ${v}` : c.op === 'add' ? `${c.field} grows by ${v}` : `${c.field} shrinks by ${v}`; +}; +export const describeStatefulRule = (action, r) => + `${r.when.length ? `When ${describeStatefulConditions(r.when)}, ` : ''}${action} answers ${r.then}${r.change.length ? ` and ${r.change.map(describeChange).join(', ')}` : ''}.`; +export const describeStatefulProperty = (p) => + p.action + ? `${p.action} ${p.kind === 'never' ? 'never' : 'always'} answers ${p.then}${p.when.length ? ` when ${describeStatefulConditions(p.when)}` : ''}.` + : p.kind === 'always' + ? `In every reachable state, ${describeStatefulConditions(p.when)}.` + : `No reachable state has ${describeStatefulConditions(p.when)}.`; + +// --------------------------------------------------------------------------- +// Evaluation: the same semantics the rendered model has. +// --------------------------------------------------------------------------- + +/** The start state: field name to a choice word or a BigInt. */ +export const initialState = (spec) => Object.fromEntries(spec.state.map((f) => [f.name, f.kind === 'choice' ? f.start : BigInt(f.start)])); + +const operand = (env, value) => (typeof value === 'object' ? env[value.field] : BigInt(value)); + +export function holdsIn(cond, env) { + const left = env[cond.field]; + switch (cond.op) { + case 'is': return left === cond.value; + case 'is not': return left !== cond.value; + case '<': return left < operand(env, cond.value); + case '<=': return left <= operand(env, cond.value); + case '>': return left > operand(env, cond.value); + case '>=': return left >= operand(env, cond.value); + case '=': return left === operand(env, cond.value); + case '!=': return left !== operand(env, cond.value); + default: throw new Error(`unknown op ${cond.op}`); + } +} + +/** Whether a change keeps its state value within bounds, read in `env` (the state before the step and the inputs). */ +export function changeFits(spec, change, env) { + const f = spec.state.find((x) => x.name === change.field); + if (f.kind === 'choice') return true; + const v = operand(env, change.value); + const old = env[change.field]; + const min = BigInt(f.min ?? 0); + const max = BigInt(f.max); + if (change.op === 'set') return v >= min && v <= max; + if (change.op === 'add') return old + v <= max; + return v + min <= old; +} + +function applyChange(change, env) { + if (change.op === 'set') return typeof change.value === 'object' ? env[change.value.field] : typeof change.value === 'number' ? BigInt(change.value) : change.value; + const v = operand(env, change.value); + return change.op === 'add' ? env[change.field] + v : env[change.field] - v; +} + +/** One action on a state: `{ state, outcome, rule }`, the rule null for otherwise. */ +export function act(spec, state, action, inputs) { + const env = { ...state, ...inputs }; + for (const rule of action.rules) { + if (rule.when.every((c) => holdsIn(c, env)) && rule.change.every((c) => changeFits(spec, c, env))) { + const next = { ...state }; + for (const c of rule.change) next[c.field] = applyChange(c, env); + return { state: next, outcome: rule.then, rule: rule.id }; + } + } + return { state, outcome: action.otherwise, rule: null }; +} + +/** One step's text, decoded as the model reads it: `{ action, inputs }`, or null when malformed. */ +export function decodeStep(spec, text) { + const parts = text.split(' '); + const action = spec.actions.find((a) => a.name === parts[0]); + if (!action || parts.length !== action.inputs.length + 1) return null; + const inputs = {}; + for (const [i, f] of action.inputs.entries()) { + const part = parts[i + 1]; + if (f.kind === 'choice') { + if (!f.values.includes(part)) return null; + inputs[f.name] = part; + } else { + const n = parseNumber(part); + if (n === null || (f.min !== undefined && n < BigInt(f.min)) || (f.max !== undefined && n > BigInt(f.max))) return null; + inputs[f.name] = n; + } + } + return { action, inputs }; +} + +export const encodeStep = (action, inputs) => [action.name, ...action.inputs.map((f) => String(inputs[f.name]))].join(' '); + +/** Each step of a session from the start, `{ outcome, rule, state }`; a malformed step answers invalid and every later step does too. */ +export function runSession(spec, steps) { + let state = initialState(spec); + let broken = false; + return steps.map((text) => { + const decoded = broken ? null : decodeStep(spec, text); + if (!decoded) { + broken = true; + return { outcome: INVALID, rule: null, state }; + } + const r = act(spec, state, decoded.action, decoded.inputs); + state = r.state; + return r; + }); +} + +/** The answer text of a state after a step: the outcome, then each state value as `name=value`. */ +export const answerText = (spec, outcome, state) => [outcome, ...spec.state.map((f) => `${f.name}=${state[f.name]}`)].join(' '); + +export function sessionLimits(spec) { + const valueWidth = (f) => (f.kind === 'choice' ? Math.max(...f.values.map((v) => v.length)) : String(f.max).length); + const responseMaximum = Math.max(64, Math.max(...spec.outcomes.map((o) => o.length), INVALID.length) + spec.state.reduce((n, f) => n + 2 + f.name.length + valueWidth(f), 0)); + return { requestMaximum: SESSION_BYTES, responseMaximum, guestAllocationMaximum: SESSION_BYTES * 2 }; +} + +/** The whole dispatch over bytes: what the guest answers to a session, its steps separated by `;`. */ +export function respondSession(spec, bytes) { + if (bytes.length === 0 || bytes.length > SESSION_BYTES) return INVALID; + let text; + try { + text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); + } catch { + return INVALID; + } + let state = initialState(spec); + let last = null; + for (const step of text.split(';')) { + const decoded = decodeStep(spec, step); + if (!decoded) return INVALID; + const r = act(spec, state, decoded.action, decoded.inputs); + state = r.state; + last = r.outcome; + } + return answerText(spec, last, state); +} + +// --------------------------------------------------------------------------- +// Search: reachable states, for counterexamples before Lean is asked. +// --------------------------------------------------------------------------- + +/** Candidate inputs of an action: every choice, and every number on an edge of a comparison, a change or a bound. */ +function inputCandidates(spec, action) { + const constants = new Set([0n, 1n, 2n]); + const add = (n) => { + for (const d of [-1n, 0n, 1n]) if (BigInt(n) + d >= 0n && BigInt(n) + d <= NAT_MAX) constants.add(BigInt(n) + d); + }; + for (const f of [...spec.state, ...action.inputs]) { + if (f.min !== undefined) add(f.min); + if (f.max !== undefined) add(f.max); + } + for (const r of action.rules) for (const c of [...r.when, ...r.change]) if (typeof c.value === 'number') add(c.value); + for (const p of spec.properties) for (const c of p.when) if (typeof c.value === 'number') add(c.value); + const sorted = [...constants].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)); + const lists = action.inputs.map((f) => (f.kind === 'choice' ? f.values : sorted.filter((n) => (f.min === undefined || n >= BigInt(f.min)) && (f.max === undefined || n <= BigInt(f.max))))); + const out = []; + const walk = (i, acc) => { + if (out.length >= 64) return; + if (i === lists.length) return void out.push({ ...acc }); + for (const v of lists[i]) walk(i + 1, { ...acc, [action.inputs[i].name]: v }); + }; + walk(0, {}); + return out; +} + +const stateKey = (spec, state) => spec.state.map((f) => String(state[f.name])).join(' '); + +/** + * Reachable states, breadth first from the start, each with the shortest + * session found to reach it, up to `limit` states. + */ +export function reachableStates(spec, limit = 4000) { + const start = initialState(spec); + const seen = new Map([[stateKey(spec, start), { state: start, steps: [] }]]); + const queue = [seen.get(stateKey(spec, start))]; + const moves = spec.actions.map((a) => ({ action: a, inputs: inputCandidates(spec, a) })); + while (queue.length && seen.size < limit) { + const { state, steps } = queue.shift(); + for (const { action, inputs: list } of moves) { + for (const inputs of list) { + const r = act(spec, state, action, inputs); + const key = stateKey(spec, r.state); + if (seen.has(key)) continue; + const entry = { state: r.state, steps: [...steps, encodeStep(action, inputs)] }; + seen.set(key, entry); + queue.push(entry); + if (seen.size >= limit) break; + } + } + } + return [...seen.values()]; +} + +/** + * A session that breaks the property, or null when none of the reachable + * states sampled does. `{ steps, outcome?, checked }`. + */ +export function statefulCounterexample(spec, property) { + const states = reachableStates(spec); + let checked = 0; + for (const { state, steps } of states) { + if (!property.action) { + checked++; + const all = property.when.every((c) => holdsIn(c, state)); + if (property.kind === 'always' ? !all : all) return { steps, checked, state: stateKey(spec, state) }; + continue; + } + const action = spec.actions.find((a) => a.name === property.action); + for (const inputs of inputCandidates(spec, action)) { + checked++; + if (!property.when.every((c) => holdsIn(c, { ...state, ...inputs }))) continue; + const r = act(spec, state, action, inputs); + const broken = property.kind === 'never' ? r.outcome === property.then : r.outcome !== property.then; + if (broken) return { steps: [...steps, encodeStep(action, inputs)], outcome: r.outcome, rule: r.rule, checked }; + } + } + return { steps: null, checked }; +} + +export { inputCandidates }; diff --git a/studio/tools/kernel.mjs b/studio/tools/kernel.mjs index 79262cce..2fb5f938 100644 --- a/studio/tools/kernel.mjs +++ b/studio/tools/kernel.mjs @@ -25,7 +25,7 @@ import os from "node:os"; import path from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; -const PRISM_CODE = "0.8.0"; +const PRISM_CODE = "0.9.2"; const root = path.join(path.dirname(fileURLToPath(import.meta.url)), ".."); const rev = path.join(root, "KERNEL_REV"); const dir = path.join(root, "shell", "kernel"); diff --git a/studio/tools/prism_journey.mjs b/studio/tools/prism_journey.mjs index 8c6a5686..5d639ff7 100644 --- a/studio/tools/prism_journey.mjs +++ b/studio/tools/prism_journey.mjs @@ -11,6 +11,11 @@ // shell/prism/render.mjs src/journey/render.mjs (the model renderer) // shell/prism/session.mjs src/journey/session.mjs (the spec compiler the // builder, shell/prism/builder, checks a spec with) +// shell/prism/stateful.mjs src/journey/stateful.mjs (prism/spec/2, which the checker, +// shell/prism/render-stateful.mjs src/journey/render-stateful.mjs renderer and compiler import since 0.9.0) +// shell/prism/complete.mjs src/journey/complete.mjs (the draft form: a rules-only draft +// completed the same way every time; not yet called by the shell) +// shell/prism/spec-schema.mjs src/journey/spec-schema.mjs (the JSON schemas of a draft and a spec) // shell/prism/lex/Foundation/Bytes.lex.tex templates/text-request/src/Foundation/Bytes.lex.tex // shell/prism/lex/Foundation/View/Text/V1/Model.lex.tex templates/text-request/src/Foundation/View/Text/V1/Model.lex.tex // shell/prism/template.mjs src/journey/template.mjs (the GitHub template writer) @@ -32,13 +37,17 @@ import os from "node:os"; import path from "node:path"; import { fileURLToPath } from "node:url"; -const PRISM_CODE = "0.8.0"; +const PRISM_CODE = "0.9.2"; const root = path.join(path.dirname(fileURLToPath(import.meta.url)), ".."); const FILES = [ ["src/journey/spec.mjs", "shell/prism/spec.mjs"], ["src/journey/spec-file.mjs", "shell/prism/spec-file.mjs"], ["src/journey/render.mjs", "shell/prism/render.mjs"], ["src/journey/session.mjs", "shell/prism/session.mjs"], + ["src/journey/stateful.mjs", "shell/prism/stateful.mjs"], + ["src/journey/render-stateful.mjs", "shell/prism/render-stateful.mjs"], + ["src/journey/complete.mjs", "shell/prism/complete.mjs"], + ["src/journey/spec-schema.mjs", "shell/prism/spec-schema.mjs"], ["templates/text-request/src/Foundation/Bytes.lex.tex", "shell/prism/lex/Foundation/Bytes.lex.tex"], ["templates/text-request/src/Foundation/View/Text/V1/Model.lex.tex", "shell/prism/lex/Foundation/View/Text/V1/Model.lex.tex"], ["src/journey/template.mjs", "shell/prism/template.mjs"], @@ -48,7 +57,7 @@ const FILES = [ ["templates/text-request/prismpm.toml", "shell/prism/text-request/prismpm.toml"], ]; // Everything src/browser.mjs reaches, statically or through index.mjs's browser branch. -for (const file of ["browser.mjs", "index.mjs", "archive.mjs", "errors.mjs", "blake3.mjs", "attestations.mjs", "view.mjs", "core.mjs", "capabilities.mjs", "closure.mjs", "sha256.mjs", "inspect.mjs", "vendor/verify.mjs", "verify.mjs", "replay.mjs", "version.mjs", "middleware.mjs", "containers.mjs", "canonical/index.js", "tracing.mjs", "manifest.mjs", "toml.mjs", "provenance.mjs"]) FILES.push(["src/" + file, "shell/prism-code/src/" + file]); +for (const file of ["browser.mjs", "index.mjs", "archive.mjs", "errors.mjs", "blake3.mjs", "attestations.mjs", "view.mjs", "core.mjs", "capabilities.mjs", "closure.mjs", "sha256.mjs", "inspect.mjs", "vendor/verify.mjs", "verify.mjs", "replay.mjs", "version.mjs", "middleware.mjs", "containers.mjs", "canonical/index.js", "tracing.mjs", "manifest.mjs", "toml.mjs", "provenance.mjs", "uorc.mjs"]) FILES.push(["src/" + file, "shell/prism-code/src/" + file]); // Node imports the browser has not: each file's substitutions, applied in order. template.mjs and // spec-file.mjs hash through node:crypto, and spec-file.mjs reads blake3 from prism-code's own graph, // which the shell keeps under prism-code/src. diff --git a/studio/tools/prism_template.mjs b/studio/tools/prism_template.mjs index 6e888ae2..ee000648 100644 --- a/studio/tools/prism_template.mjs +++ b/studio/tools/prism_template.mjs @@ -14,7 +14,7 @@ import os from "node:os"; import path from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; -const PRISM_CODE = "0.8.0"; +const PRISM_CODE = "0.9.2"; const TEMPLATE = "a7a3041cd85d745bb2d6dfc7ee72513185fa48be"; // UOR-Foundation/template main, 2026-11-10 const READ = ["app/lexlean.lock", "app/lean-toolchain", "model/ids.toml", "CONFORMANCE.md", "site/app.json"]; const EXAMPLE = ["app/src/Contract.lex.tex", "crates/conformance/tests/contract.rs", "features/suites/contract.feature"]; From 4a4607bf846a82ae3314e2a7fac85aaaf019e9c8 Mon Sep 17 00:00:00 2001 From: humuhumu33 <68450279+humuhumu33@users.noreply.github.com> Date: Mon, 16 Nov 2026 13:06:10 +0000 Subject: [PATCH 2/2] Keep the shell on the newest prism-code: an hourly re-pin opened as a pull request Co-Authored-By: Claude Fable 5.2 --- .github/workflows/prism-code-update.yml | 114 ++++++++++++++++++++++++ studio/tools/prism_code_update.mjs | 67 ++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 .github/workflows/prism-code-update.yml create mode 100644 studio/tools/prism_code_update.mjs diff --git a/.github/workflows/prism-code-update.yml b/.github/workflows/prism-code-update.yml new file mode 100644 index 00000000..82dc44f7 --- /dev/null +++ b/.github/workflows/prism-code-update.yml @@ -0,0 +1,114 @@ +# Keeps the shell on the newest prism-code, without giving up the pin. Each hour it asks npm which +# release of prism-code is `latest`. When that is newer than the version the shell carries byte for +# byte, it re-pins (studio/tools/prism_code_update.mjs), runs the gates a re-pin must keep, and opens +# the result as a pull request. Nothing is merged here: a pull request the workflow token opens +# starts no CI, so a person, or the acceptance gate dispatched on it, decides. +# +# The proposal is made with read permission only, as template-update.yml makes its own: the job that +# installs a package published minutes ago holds no token that can write. The job that can write +# applies the patch that came out and runs nothing from it. +name: prism-code update + +on: + schedule: + - cron: '41 * * * *' + workflow_dispatch: + +permissions: {} + +concurrency: + group: prism-code-update + cancel-in-progress: false + +jobs: + proposal: + name: re-pin prism-code to npm's latest and hold it to the journey gates + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + outputs: + changed: ${{ steps.repin.outputs.changed }} + version: ${{ steps.repin.outputs.version }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + with: + persist-credentials: false + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: "24" + - id: repin + name: Re-pin, copy the files, and check every import resolves inside the shell + working-directory: studio + run: | + set -euo pipefail + node tools/prism_code_update.mjs + if git diff --quiet; then + echo "changed=false" >> "$GITHUB_OUTPUT" + exit 0 + fi + echo "changed=true" >> "$GITHUB_OUTPUT" + echo "version=$(sed -n 's/^const PRISM_CODE = "\(.*\)";$/\1/p' tools/prism_journey.mjs)" >> "$GITHUB_OUTPUT" + - name: The commit Forge makes on a template instance is still prism-code's, byte for byte + if: steps.repin.outputs.changed == 'true' + working-directory: studio + run: node tools/prism_template.mjs --check + - name: Every app the studio publishes is still a full Prism model + if: steps.repin.outputs.changed == 'true' + working-directory: studio + run: | + node tools/builder/pack.mjs --check + node --test tools/builder_commit.test.mjs + - name: Keep the re-pin as an inert patch + if: steps.repin.outputs.changed == 'true' + run: | + git add --intent-to-add studio + git diff --binary > .prism-code-update.patch + - if: steps.repin.outputs.changed == 'true' + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 + with: + name: prism-code-update-proposal + path: .prism-code-update.patch + if-no-files-found: error + include-hidden-files: true + + open: + name: open the re-pin as a pull request + needs: proposal + if: needs.proposal.outputs.changed == 'true' + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: write + pull-requests: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + with: + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 + with: + name: prism-code-update-proposal + - name: Apply the patch without executing anything from it + run: | + git apply --check .prism-code-update.patch + git apply .prism-code-update.patch + rm .prism-code-update.patch + - uses: peter-evans/create-pull-request@15733dbdfeedb4f7fdb73d13c6f5ac83b710fab8 + with: + branch: automation/prism-code-update + commit-message: "chore: re-pin prism-code to ${{ needs.proposal.outputs.version }}" + delete-branch: true + title: "chore: re-pin prism-code to ${{ needs.proposal.outputs.version }}" + body: | + npm's `latest` release of prism-code is ${{ needs.proposal.outputs.version }}, newer than the + version the shell carried. This re-pins the three tools that name it and copies its + journey and browser files byte for byte (`studio/tools/prism_code_update.mjs`). + + Held before this was opened: every copied file is that version's, every import the + copied files make resolves inside the shell, the template commit is still prism-code's + byte for byte, and the builder gates pass. + + Not run here: the rest of the studio gates. A pull request the workflow token opens + starts no CI, so dispatch them on this branch, and read the prism-code changelog for + anything the shell should start to call, before merging. diff --git a/studio/tools/prism_code_update.mjs b/studio/tools/prism_code_update.mjs new file mode 100644 index 00000000..470c3c53 --- /dev/null +++ b/studio/tools/prism_code_update.mjs @@ -0,0 +1,67 @@ +// Keep the shell on the newest prism-code, without giving up the pin. +// +// The shell carries prism-code's journey and browser files byte for byte at one version +// (tools/prism_journey.mjs), and three tools name that version. This re-pins all three to the +// version npm calls `latest`, copies the files at it, and holds the result to what a re-pin must +// keep true: every file is that version's, and every import the copied files make resolves inside +// the shell, so a file a new version started to import is noticed here and not in a browser. +// +// node tools/prism_code_update.mjs re-pin to npm's latest, if it is newer +// node tools/prism_code_update.mjs --check say whether the pin is behind; exit 1 if it is +// node tools/prism_code_update.mjs 0.9.2 re-pin to this version +import { execFileSync } from "node:child_process"; +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const root = path.join(path.dirname(fileURLToPath(import.meta.url)), ".."); +const PINS = ["tools/prism_journey.mjs", "tools/kernel.mjs", "tools/prism_template.mjs"]; +const PIN = /^const PRISM_CODE = "(\d+\.\d+\.\d+)";$/m; +const read = (file) => fs.readFileSync(path.join(root, file), "utf8"); +const run = (command, args, options = {}) => execFileSync(command, args, { cwd: root, encoding: "utf8", shell: process.platform === "win32", ...options }); + +const pinned = PINS.map((file) => { + const found = PIN.exec(read(file)); + if (!found) throw new Error(`${file} names no prism-code version`); + return found[1]; +}); +if (new Set(pinned).size !== 1) throw new Error(`the tools disagree on the prism-code version: ${PINS.map((f, i) => `${f} ${pinned[i]}`).join(", ")}`); +const current = pinned[0]; +const wanted = /^\d+\.\d+\.\d+$/.test(process.argv[2] ?? "") ? process.argv[2] : run("npm", ["view", "prism-code", "version"]).trim(); +if (!/^\d+\.\d+\.\d+$/.test(wanted)) throw new Error(`npm names no release of prism-code: ${wanted}`); +const older = (a, b) => a.split(".").map(Number).reduce((r, n, i) => r || n - Number(b.split(".")[i]), 0) < 0; + +if (process.argv[2] === "--check") { + console.log(older(current, wanted) ? `prism-code: pinned ${current}, npm has ${wanted}` : `prism-code: ${current} is the latest`); + process.exit(older(current, wanted) ? 1 : 0); +} +if (!older(current, wanted)) { + console.log(`prism-code: ${current} is the latest; nothing to do`); + process.exit(0); +} +for (const file of PINS) fs.writeFileSync(path.join(root, file), read(file).replace(PIN, `const PRISM_CODE = "${wanted}";`)); +run(process.execPath, ["tools/prism_journey.mjs"], { stdio: "inherit", shell: false }); +run(process.execPath, ["tools/prism_journey.mjs", "--check"], { stdio: "inherit", shell: false }); + +// A new version may import a file the copy list does not name yet. The imports already unresolved +// before the re-pin are Node's branch of index.mjs, which no browser takes; anything else is new. +const KNOWN = new Set(["volumes.mjs", "session.mjs", "networks.mjs", "system.mjs", "verify-namespace.mjs", "errors-namespace.mjs", "node.mjs", "images-namespace.mjs"]); +const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(path.join(dir, e.name)) : e.name.endsWith(".mjs") ? [path.join(dir, e.name)] : [])); +const missing = []; +for (const dir of ["shell/prism-code/src", "shell/prism"]) { + for (const file of walk(path.join(root, dir))) { + for (const found of fs.readFileSync(file, "utf8").matchAll(/(?:from|import\()\s*['"]([^'"]+)['"]/g)) { + const name = found[1]; + const where = path.relative(root, file).split(path.sep).join("/"); + if (name.startsWith("node:") && dir === "shell/prism") missing.push(`${where} imports ${name}: add its substitution to SUBSTITUTE in tools/prism_journey.mjs`); + else if (name.startsWith(".") && !fs.existsSync(path.join(path.dirname(file), name)) && !(dir === "shell/prism-code/src" && KNOWN.has(path.basename(name)))) { + missing.push(`${where} imports ${name}: add it to FILES in tools/prism_journey.mjs`); + } + } + } +} +if (missing.length) { + console.error(`prism-code ${wanted} needs files the shell does not carry:\n ${missing.join("\n ")}`); + process.exit(1); +} +console.log(`prism-code: re-pinned ${current} -> ${wanted}; every copied file's imports resolve inside the shell`);