@tiinex/core 0.1.1

package/src/tooling/portable/orchestration/task.prepare.js

@@ -0,0 +1,191 @@
+import { portableFinding, summarizePortableFindings } from '../findings.js';
+import { discoverPortableHostCapabilities, portableTaskRoute } from '../host/host.capabilities.js';
+import { resolvePortableSchemaChainMaterial } from '../providers/schema.providers.js';
+import { buildPortableSchemaGuide, planPortableArtifact } from '../schema/schema.guide.js';
+import { validatePortableDraft } from '../draft/draft.operations.js';
+import { searchPortableLineage } from '../lineage/lineage.search.js';
+import { preparePortableAssetAnalysis } from '../assets/asset.operations.js';
+import { planPortableHostAction } from '../host/tool.bindings.js';
+import { describePortableCheckpointGate, qualifyPortableCheckpoint } from '../conformance/checkpoint.qualification.js';
+
+export const PORTABLE_TASK_PREPARATION_SCHEMA_ID = 'tiinex.portable.task-preparation.v1';
+
+export async function preparePortableTask(input = {}, options = {}) {
+  const task = normalizeTask(input.task || input.intent || input.goal || options.task || 'inspect');
+  const hostDiscovery = discoverPortableHostCapabilities(input.host || input, options.host || options);
+  const findings = [...(hostDiscovery.findings || [])];
+  const route = portableTaskRoute(routeTask(task), hostDiscovery.profile);
+  let result = null;
+  let status = 'ready';
+  let nextAction = null;
+
+  if (['read-schema', 'create-artifact', 'validate-draft'].includes(task)) {
+    const schemaId = String(input.schemaId || options.schemaId || '').trim();
+    if (!schemaId) findings.push(portableFinding('error', 'portable.task.schema.required', `Task ${task} requires a schema id.`));
+    if (schemaId) {
+      const chain = await resolvePortableSchemaChainMaterial({ ...input, schemaId }, options);
+      findings.push(...(chain.findings || []));
+      if (chain.status === 'provider-action-required') {
+        status = 'provider-action-required';
+        const hostActionPlan = planPortableHostAction({ ...input, action: 'repository-schema-resolution', request: chain.providerRequest, host: input.host || input }, options);
+        findings.push(...(hostActionPlan.findings || []));
+        nextAction = Object.freeze({ ...chain.providerRequest, hostActionPlan });
+        result = Object.freeze({ schemaChain: chain, hostActionPlan });
+      } else {
+        const context = { ...input, files: chain.materials.files, schemaCache: chain.materials.schemaCache, schemaId };
+        if (task === 'read-schema') {
+          const guide = buildPortableSchemaGuide({ ...context, task: input.schemaTask || 'read', detail: input.detail || 'compact' }, options);
+          findings.push(...(guide.findings || []));
+          result = Object.freeze({ schemaChain: chain, guide: guide.guide });
+          status = guide.findings.some((finding) => finding.severity === 'error') ? 'blocked' : 'ready';
+          nextAction = Object.freeze({ operation: 'schema-guide', reason: 'Readable schema material is resolved and a compact guide is available.' });
+        } else if (task === 'create-artifact') {
+          const plan = planPortableArtifact({ ...context, task: 'create', values: input.values || input.inputs || {} }, options);
+          findings.push(...(plan.findings || []));
+          result = Object.freeze({ schemaChain: chain, guide: plan.guide, plan: plan.plan });
+          status = plan.plan.readyToDraft ? 'ready-to-create-local-draft' : 'authoring-input-required';
+          nextAction = Object.freeze({
+            operation: plan.plan.readyToDraft ? 'create-local-draft' : 'collect-required-inputs',
+            missingInputs: plan.plan.missingInputs,
+            conditionReviewRequired: plan.plan.conditionReviewRequired
+          });
+        } else {
+          const validation = validatePortableDraft({ ...context, markdown: input.markdown || input.draft?.markdown || '', path: input.path || input.draft?.path || 'draft.md' }, options);
+          findings.push(...(validation.findings || []));
+          result = Object.freeze({ schemaChain: chain, validation });
+          status = validation.status;
+          nextAction = Object.freeze({ operation: validation.status === 'clean' ? 'stage-draft' : 'repair-plan' });
+        }
+      }
+    }
+  } else if (task === 'search-lineage') {
+    const search = searchPortableLineage(input, options);
+    findings.push(...(search.findings || []));
+    result = Object.freeze({ search });
+    status = 'ready';
+    nextAction = Object.freeze({ operation: 'search-lineage', returnedMatches: search.matches.length, totalMatches: search.page.total });
+  } else if (task === 'analyze-asset') {
+    const prepared = preparePortableAssetAnalysis(input, options);
+    findings.push(...(prepared.findings || []));
+    result = Object.freeze({ assetAnalysis: prepared });
+    status = prepared.status;
+    const action = prepared.request?.requiredCapability === 'multimodal.pdf' ? 'pdf-analysis' : 'image-analysis';
+    const hostActionPlan = prepared.request ? planPortableHostAction({ ...input, action, request: prepared.request, host: input.host || input }, options) : null;
+    if (hostActionPlan) findings.push(...(hostActionPlan.findings || []));
+    nextAction = prepared.request ? Object.freeze({ ...prepared.request.hostAction, hostActionPlan }) : null;
+  } else if (task === 'materialize-findings') {
+    const { planPortableDurableMaterialization } = await import('../materialization/durable.materialize.js');
+    const plan = planPortableDurableMaterialization(input);
+    findings.push(...(plan.findings || []));
+    result = Object.freeze({ materializationPlan: plan });
+    status = plan.status;
+    nextAction = Object.freeze({
+      operation: plan.status === 'ready' ? 'materialize-durable-findings' : 'collect-materialization-map',
+      unassignedFindings: plan.unassignedFindings?.length || 0
+    });
+  } else if (task === 'qualify-checkpoint') {
+    if (Array.isArray(input.receipts) && input.receipts.length) {
+      const qualification = qualifyPortableCheckpoint(input);
+      findings.push(...(qualification.findings || []));
+      result = Object.freeze({ qualification });
+      status = qualification.status;
+      nextAction = Object.freeze({
+        operation: qualification.status === 'qualified' || qualification.status === 'qualified-with-warnings' ? 'review-checkpoint-qualification' : 'run-or-repair-checkpoint-gates',
+        gateSummary: qualification.gateSummary
+      });
+    } else {
+      const checkpointGate = describePortableCheckpointGate({ profile: input.profile || 'source-clean' });
+      result = Object.freeze({ checkpointGate });
+      status = 'receipt-required';
+      nextAction = Object.freeze({
+        operation: 'run-checkpoint-gates',
+        adapter: 'tools/tiinex-portable-verify.mjs',
+        profile: checkpointGate.profile,
+        commandsExecutedByPortableCore: false
+      });
+    }
+  } else if (task === 'checkpoint') {
+    const session = input.session || input.snapshot || input;
+    result = Object.freeze({
+      sessionSummary: Object.freeze({
+        stagedArtifacts: session.stagedArtifacts?.length || 0,
+        durableFindings: session.durableFindings?.length || 0,
+        schemaCacheEntries: session.schemaCache?.length || 0
+      })
+    });
+    status = 'ready';
+    nextAction = Object.freeze({ operation: 'create-checkpoint', canonicalHandoffArtifact: false });
+  } else if (task === 'package') {
+    const session = input.session || input.snapshot || {};
+    const stagedCount = (input.stagedArtifacts || session.stagedArtifacts || []).length;
+    result = Object.freeze({ stagedArtifacts: stagedCount, runtimeContract: 'tiinex.export.package.bundle.v1', canonicalPackageSchemaLocked: false });
+    status = stagedCount ? 'ready' : 'material-required';
+    nextAction = Object.freeze({ operation: stagedCount ? 'build-runtime-package' : 'stage-draft', then: stagedCount ? 'roundtrip-runtime-package' : 'build-runtime-package' });
+  } else {
+    result = Object.freeze({
+      operations: Object.freeze(['inspect', 'audit', 'search-lineage', 'read-schema', 'create-artifact', 'validate-draft', 'analyze-asset', 'materialize-findings', 'qualify-checkpoint', 'checkpoint', 'package'])
+    });
+    status = task === 'inspect' ? 'ready' : 'unknown-task';
+    nextAction = Object.freeze({ operation: task === 'inspect' ? 'inspect' : 'discover-tooling' });
+  }
+
+  const summary = summarizePortableFindings(findings);
+  if (summary.counts.error && status !== 'provider-action-required') status = 'blocked';
+  return Object.freeze({
+    schema: PORTABLE_TASK_PREPARATION_SCHEMA_ID,
+    task,
+    status,
+    route,
+    host: hostDiscovery.profile,
+    result,
+    nextAction,
+    boundary: Object.freeze({
+      remoteFetch: 'host-mediated-only',
+      remoteWrite: false,
+      sourceMutation: false,
+      hiddenChatStateIsProvenance: false
+    }),
+    findings: Object.freeze(findings),
+    findingSummary: summary
+  });
+}
+
+function normalizeTask(value = '') {
+  const task = String(value || '').trim().toLowerCase().replace(/[_\s]+/g, '-');
+  const aliases = {
+    create: 'create-artifact',
+    write: 'create-artifact',
+    'create-draft': 'create-artifact',
+    schema: 'read-schema',
+    'resolve-schema': 'read-schema',
+    validate: 'validate-draft',
+    repair: 'validate-draft',
+    search: 'search-lineage',
+    lineage: 'search-lineage',
+    image: 'analyze-asset',
+    asset: 'analyze-asset',
+    'analyze-image': 'analyze-asset',
+    materialize: 'materialize-findings',
+    'materialize-durable-findings': 'materialize-findings',
+    qualify: 'qualify-checkpoint',
+    verify: 'qualify-checkpoint',
+    'verify-checkpoint': 'qualify-checkpoint',
+    checkpoint: 'checkpoint',
+    package: 'package',
+    'build-package': 'package'
+  };
+  return aliases[task] || task || 'inspect';
+}
+
+function routeTask(task) {
+  if (task === 'read-schema') return 'resolve-unknown-schema';
+  if (task === 'create-artifact') return 'create-local-draft';
+  if (task === 'validate-draft') return 'create-local-draft';
+  if (task === 'search-lineage') return 'search-lineage';
+  if (task === 'analyze-asset') return 'analyze-image-asset';
+  if (task === 'materialize-findings') return 'materialize-durable-findings';
+  if (task === 'qualify-checkpoint') return 'qualify-checkpoint';
+  if (task === 'checkpoint') return 'create-checkpoint';
+  if (task === 'package') return 'build-runtime-package';
+  return 'load-material';
+}

package/src/tooling/portable/output/artifact.result.package.js

@@ -0,0 +1,308 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createDeterministicStoredZip, safeZipPath } from './deterministic.zip.js';
+
+export const PORTABLE_ARTIFACT_RESULT_PACKAGE_SCHEMA_ID = 'tiinex.portable.artifact-result-package.v1';
+export const PORTABLE_ARTIFACT_CREATION_RECEIPT_SCHEMA_ID = 'tiinex.portable.artifact-creation-receipt.v1';
+export const PORTABLE_ARTIFACT_INPUT_SNAPSHOT_SCHEMA_ID = 'tiinex.portable.artifact-input-snapshot.v1';
+export const PORTABLE_ARTIFACT_OPERATION_RECEIPT_SCHEMA_ID = 'tiinex.portable.artifact-operation-receipt.v1';
+export const PORTABLE_ARTIFACT_RESULT_CHECKSUM_SCHEMA_ID = 'tiinex.portable.artifact-result-checksums.v1';
+export const PORTABLE_ARTIFACT_RESULT_WRITE_RECEIPT_SCHEMA_ID = 'tiinex.portable.artifact-result-package-write-receipt.v1';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const RESULT_VERIFIER_SOURCE = path.resolve(MODULE_DIR, '../bootstrap/artifact.result.selfverify.mjs');
+
+export async function writePortableArtifactResultPackage(result = {}, outputPath = '', context = {}) {
+  const target = path.resolve(String(outputPath || '').trim());
+  if (!String(outputPath || '').trim()) throw new Error('portable.artifact-result.path.required');
+  assertCleanCreation(result, context.writeReceipt);
+
+  const createdAt = normalizeCreatedAt(context.createdAt);
+  const artifact = normalizeMarkdown(result.draft.markdown);
+  const artifactSha256 = sha256(artifact);
+  const inputSnapshot = buildInputSnapshot(context.creationInput || {}, createdAt);
+  const inputSnapshotBytes = stableJson(inputSnapshot);
+  const inputSnapshotSha256 = sha256(inputSnapshotBytes);
+  const operationReceipt = buildOperationReceipt(result, artifactSha256, createdAt);
+  const operationReceiptBytes = stableJson(operationReceipt);
+  const writeReceipt = cloneJson(context.writeReceipt);
+  const writeReceiptBytes = stableJson(writeReceipt);
+  const transferManifest = requireObject(context.transferManifest, 'portable.artifact-result.transfer-manifest.required');
+  const bootstrapManifest = requireObject(context.bootstrapManifest, 'portable.artifact-result.bootstrap-manifest.required');
+  const transferVerification = requireValidVerification(context.transferVerification, 'tiinex.llm.transfer.verification.v1', 'portable.artifact-result.transfer-verification');
+  const bootstrapVerification = requireValidVerification(context.bootstrapVerification, ['tiinex.bootstrap.verification.v2', 'tiinex.bootstrap.archive-verification.v2'], 'portable.artifact-result.bootstrap-verification');
+  const taskRequest = normalizeMarkdown(String(context.taskRequest || '').trim());
+  if (!String(context.taskRequest || '').trim()) throw new Error('portable.artifact-result.task-request.required');
+  const transferManifestBytes = stableJson(transferManifest);
+  const bootstrapManifestBytes = stableJson(bootstrapManifest);
+  const transferVerificationBytes = exactJsonBytes(context.transferVerificationBytes, transferVerification, 'portable.artifact-result.transfer-verification-bytes');
+  const bootstrapVerificationBytes = exactJsonBytes(context.bootstrapVerificationBytes, bootstrapVerification, 'portable.artifact-result.bootstrap-verification-bytes');
+  const identities = qualifyContextIdentities({ transferManifest, bootstrapManifest, transferVerification, bootstrapVerification, transferVerificationBytes, bootstrapVerificationBytes, taskRequest });
+
+  const creationReceipt = Object.freeze({
+    schema: PORTABLE_ARTIFACT_CREATION_RECEIPT_SCHEMA_ID,
+    version: 1,
+    status: 'packaged-local-clean',
+    createdAt,
+    operation: 'create-local-draft',
+    artifact: Object.freeze({
+      packagePath: 'artifact.trace.md',
+      logicalPath: String(result.draft.path || ''),
+      schemaId: String(result.draft.schemaId || result.schemaId || ''),
+      bytes: Buffer.byteLength(artifact, 'utf8'),
+      sha256: artifactSha256,
+      validationStatus: String(result.validation?.status || '')
+    }),
+    inputSnapshot: Object.freeze({
+      packagePath: 'artifact.input.snapshot.json',
+      sha256: inputSnapshotSha256
+    }),
+    operationReceipt: Object.freeze({
+      packagePath: 'artifact.operation.receipt.json',
+      sha256: sha256(operationReceiptBytes),
+      status: operationReceipt.status
+    }),
+    writeReceipt: Object.freeze({
+      packagePath: 'artifact.write.receipt.json',
+      sha256: sha256(writeReceiptBytes),
+      status: String(writeReceipt.status || '')
+    }),
+    context: identities,
+    boundary: Object.freeze({
+      localDraft: true,
+      sourceBacked: false,
+      sourceMutation: false,
+      remoteWrite: false,
+      publication: false,
+      handoffAuthority: false
+    })
+  });
+  const creationReceiptBytes = stableJson(creationReceipt);
+  const verifier = await readFile(RESULT_VERIFIER_SOURCE);
+
+  const manifest = Object.freeze({
+    schema: PORTABLE_ARTIFACT_RESULT_PACKAGE_SCHEMA_ID,
+    version: 1,
+    boundary: 'Local Tiinex artifact plus durable creation evidence. This package is not publication, source authority, or a handoff claim.',
+    entrypoints: Object.freeze({
+      artifact: 'artifact.trace.md',
+      creationReceipt: 'artifact.creation.receipt.json',
+      inputSnapshot: 'artifact.input.snapshot.json',
+      operationReceipt: 'artifact.operation.receipt.json',
+      writeReceipt: 'artifact.write.receipt.json',
+      verifier: 'bin/verify-result.mjs',
+      checksums: 'checksums.json'
+    }),
+    artifact: creationReceipt.artifact,
+    evidence: Object.freeze({
+      creationReceipt: Object.freeze({ path: 'artifact.creation.receipt.json', sha256: sha256(creationReceiptBytes) }),
+      inputSnapshot: creationReceipt.inputSnapshot,
+      operationReceipt: creationReceipt.operationReceipt,
+      writeReceipt: creationReceipt.writeReceipt,
+      taskRequest: Object.freeze({ path: 'context/task.request.txt', sha256: sha256(taskRequest) }),
+      transferManifest: Object.freeze({ path: 'context/transfer.manifest.json', sha256: sha256(transferManifestBytes) }),
+      bootstrapManifest: Object.freeze({ path: 'context/bootstrap.manifest.json', sha256: sha256(bootstrapManifestBytes) }),
+      transferVerification: Object.freeze({ path: 'verification/transfer.json', sha256: sha256(transferVerificationBytes), status: transferVerification.status }),
+      bootstrapVerification: Object.freeze({ path: 'verification/bootstrap.json', sha256: sha256(bootstrapVerificationBytes), status: bootstrapVerification.status })
+    }),
+    context: identities,
+    trust: Object.freeze({
+      artifactCodeExecution: 'never-auto-execute',
+      verifierExecution: 'allowed',
+      sourceMutation: false,
+      remoteWrite: false
+    })
+  });
+
+  const baseEntries = [
+    fileEntry('artifact.trace.md', artifact),
+    fileEntry('artifact.creation.receipt.json', creationReceiptBytes),
+    fileEntry('artifact.input.snapshot.json', inputSnapshotBytes),
+    fileEntry('artifact.operation.receipt.json', operationReceiptBytes),
+    fileEntry('artifact.write.receipt.json', writeReceiptBytes),
+    fileEntry('context/task.request.txt', taskRequest),
+    fileEntry('context/transfer.manifest.json', transferManifestBytes),
+    fileEntry('context/bootstrap.manifest.json', bootstrapManifestBytes),
+    fileEntry('verification/transfer.json', transferVerificationBytes),
+    fileEntry('verification/bootstrap.json', bootstrapVerificationBytes),
+    fileEntry('manifest.json', stableJson(manifest)),
+    fileEntry('bin/verify-result.mjs', verifier)
+  ].sort((a, b) => a.path.localeCompare(b.path));
+  const checksums = Object.freeze({
+    schema: PORTABLE_ARTIFACT_RESULT_CHECKSUM_SCHEMA_ID,
+    version: 1,
+    algorithm: 'sha256',
+    files: Object.freeze(baseEntries.map(({ path: filePath, bytes, sha256: digest }) => Object.freeze({ path: filePath, bytes, sha256: digest })))
+  });
+  const entries = [...baseEntries, fileEntry('checksums.json', stableJson(checksums))].sort((a, b) => a.path.localeCompare(b.path));
+  const archive = createDeterministicStoredZip(entries.map((entry) => ({ name: entry.path, data: entry.content })));
+
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, archive, { flag: context.overwrite === true ? 'w' : 'wx' });
+  return Object.freeze({
+    schema: PORTABLE_ARTIFACT_RESULT_WRITE_RECEIPT_SCHEMA_ID,
+    version: 1,
+    status: 'written-local-result-package',
+    outputPath: target,
+    bytes: archive.length,
+    sha256: sha256(archive),
+    artifactSha256,
+    inputSnapshotSha256,
+    createdAt,
+    files: entries.length,
+    boundary: Object.freeze({
+      localOutput: true,
+      sourceMutation: false,
+      remoteWrite: false,
+      overwrite: context.overwrite === true
+    })
+  });
+}
+
+function assertCleanCreation(result, writeReceipt) {
+  if (result?.status !== 'created-clean') throw new Error(`portable.artifact-result.not-clean:${result?.status || 'unknown'}`);
+  if (result?.validation?.status !== 'clean') throw new Error(`portable.artifact-result.validation-not-clean:${result?.validation?.status || 'unknown'}`);
+  if (!result?.draft?.markdown) throw new Error('portable.artifact-result.markdown.required');
+  if (!String(result.draft.sourceMode || '').startsWith('local-') || result.draft.source) throw new Error('portable.artifact-result.source-boundary.invalid');
+  if (!writeReceipt || writeReceipt.status !== 'written-local-clean') throw new Error(`portable.artifact-result.write-receipt.invalid:${writeReceipt?.status || 'missing'}`);
+  if (writeReceipt.sha256 !== sha256(normalizeMarkdown(result.draft.markdown))) throw new Error('portable.artifact-result.write-receipt.sha256-mismatch');
+  if (writeReceipt.validationStatus !== 'clean') throw new Error('portable.artifact-result.write-receipt.validation-not-clean');
+}
+
+function buildInputSnapshot(input = {}, createdAt = '') {
+  return Object.freeze({
+    schema: PORTABLE_ARTIFACT_INPUT_SNAPSHOT_SCHEMA_ID,
+    version: 1,
+    capturedAt: createdAt,
+    operation: 'create-local-draft',
+    request: Object.freeze({
+      schemaId: String(input.schemaId || ''),
+      path: String(input.path || ''),
+      title: String(input.title || ''),
+      summary: String(input.summary || ''),
+      why: String(input.why || ''),
+      values: cloneJson(input.values || {}),
+      sections: cloneJson(input.sections || {}),
+      parent: boundedParent(input.parent),
+      allowIncomplete: Boolean(input.allowIncomplete)
+    }),
+    boundary: Object.freeze({
+      dialogueOrHostInput: true,
+      sourceMutation: false,
+      remoteWrite: false,
+      omittedLoadedSchemaMaterial: true
+    })
+  });
+}
+
+function buildOperationReceipt(result = {}, artifactSha256 = '', createdAt = '') {
+  return Object.freeze({
+    schema: PORTABLE_ARTIFACT_OPERATION_RECEIPT_SCHEMA_ID,
+    version: 1,
+    recordedAt: createdAt,
+    operation: String(result.operation || 'create-local-draft'),
+    status: String(result.status || ''),
+    schemaId: String(result.schemaId || result.draft?.schemaId || ''),
+    artifact: Object.freeze({
+      logicalPath: String(result.draft?.path || ''),
+      sha256: artifactSha256,
+      sourceMode: String(result.draft?.sourceMode || '')
+    }),
+    validation: cloneJson(result.validation || null),
+    qualification: cloneJson(result.qualification || null),
+    findingSummary: cloneJson(result.findingSummary || null),
+    findings: cloneJson(result.findings || [])
+  });
+}
+
+function qualifyContextIdentities({ transferManifest, bootstrapManifest, transferVerification, bootstrapVerification, transferVerificationBytes, bootstrapVerificationBytes, taskRequest }) {
+  if (transferManifest.schema !== 'tiinex.llm.transfer.package.v1') throw new Error('portable.artifact-result.transfer-manifest.schema');
+  if (bootstrapManifest.schema !== 'tiinex.bootstrap.package.v1') throw new Error('portable.artifact-result.bootstrap-manifest.schema');
+  const expected = transferManifest.expectedBootstrap || {};
+  if (expected.bootstrapVersion !== bootstrapManifest.bootstrapVersion) throw new Error('portable.artifact-result.bootstrap-version-mismatch');
+  if (expected.sourceIdentity?.runtimeFingerprint !== bootstrapManifest.sourceIdentity?.runtimeFingerprint) throw new Error('portable.artifact-result.bootstrap-runtime-mismatch');
+  if (expected.canonicalMaterial?.ref !== bootstrapManifest.canonicalMaterial?.ref || expected.canonicalMaterial?.schemaPackFingerprint !== bootstrapManifest.canonicalMaterial?.schemaPackFingerprint) throw new Error('portable.artifact-result.bootstrap-canonical-mismatch');
+  if (transferVerification.transferVersion !== transferManifest.transferVersion) throw new Error('portable.artifact-result.transfer-verification-version-mismatch');
+  const verifiedBootstrapVersion = String(bootstrapVerification.packageVersion || bootstrapVerification.bootstrapVersion || '');
+  if (verifiedBootstrapVersion !== bootstrapManifest.bootstrapVersion) throw new Error('portable.artifact-result.bootstrap-verification-version-mismatch');
+  return Object.freeze({
+    task: Object.freeze({
+      packagePath: 'context/task.request.txt',
+      sha256: sha256(taskRequest)
+    }),
+    transfer: Object.freeze({
+      manifestSha256: sha256(stableJson(transferManifest)),
+      verificationSha256: sha256(transferVerificationBytes),
+      transferVersion: String(transferManifest.transferVersion || ''),
+      profileId: String(transferManifest.profile?.id || ''),
+      verificationStatus: transferVerification.status
+    }),
+    bootstrap: Object.freeze({
+      manifestSha256: sha256(stableJson(bootstrapManifest)),
+      verificationSha256: sha256(bootstrapVerificationBytes),
+      bootstrapVersion: String(bootstrapManifest.bootstrapVersion || ''),
+      sourceIdentity: cloneJson(bootstrapManifest.sourceIdentity || {}),
+      canonicalMaterial: Object.freeze({
+        repository: String(bootstrapManifest.canonicalMaterial?.repository || ''),
+        ref: String(bootstrapManifest.canonicalMaterial?.ref || ''),
+        schemaPackFingerprint: String(bootstrapManifest.canonicalMaterial?.schemaPackFingerprint || '')
+      }),
+      verificationStatus: bootstrapVerification.status
+    })
+  });
+}
+
+function exactJsonBytes(raw, parsed, code) {
+  if (raw == null) return stableJson(parsed);
+  const bytes = Buffer.from(raw);
+  let value;
+  try { value = JSON.parse(bytes.toString('utf8')); }
+  catch { throw new Error(`${code}.json`); }
+  if (JSON.stringify(sortValue(value)) !== JSON.stringify(sortValue(parsed))) throw new Error(`${code}.mismatch`);
+  return bytes;
+}
+
+function requireValidVerification(value, schema, code) {
+  const verification = requireObject(value, `${code}.required`);
+  const allowed = Array.isArray(schema) ? schema : [schema];
+  if (!allowed.includes(verification.schema)) throw new Error(`${code}.schema`);
+  if (verification.status !== 'valid') throw new Error(`${code}.invalid:${verification.status || 'unknown'}`);
+  return cloneJson(verification);
+}
+function requireObject(value, code) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(code);
+  return cloneJson(value);
+}
+function boundedParent(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const parent = {};
+  for (const key of ['id', 'path', 'schemaId', 'parentSchemaId', 'trace', 'origin', 'boundary', 'sourceMode', 'title', 'summary']) {
+    if (value[key] !== undefined && value[key] !== null && value[key] !== '') parent[key] = value[key];
+  }
+  return Object.keys(parent).length ? Object.freeze(parent) : null;
+}
+function normalizeCreatedAt(value) {
+  const candidate = String(value || '').trim() || new Date().toISOString();
+  const parsed = new Date(candidate);
+  if (!Number.isFinite(parsed.getTime())) throw new Error(`portable.artifact-result.created-at.invalid:${candidate}`);
+  return parsed.toISOString();
+}
+function fileEntry(filePath, value) {
+  const clean = safeZipPath(filePath);
+  if (!clean || clean !== filePath) throw new Error(`portable.artifact-result.path.unsafe:${filePath}`);
+  const content = Buffer.isBuffer(value) ? Buffer.from(value) : Buffer.from(String(value ?? ''), 'utf8');
+  return Object.freeze({ path: clean, content, bytes: content.length, sha256: sha256(content) });
+}
+function normalizeMarkdown(value = '') { return `${String(value || '').replace(/\r\n/g, '\n').replace(/\s+$/u, '')}\n`; }
+function stableJson(value) { return `${JSON.stringify(sortValue(value), null, 2)}\n`; }
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (!value || typeof value !== 'object') return value;
+  const output = {};
+  for (const key of Object.keys(value).sort()) output[key] = sortValue(value[key]);
+  return output;
+}
+function cloneJson(value) { return value === undefined ? null : JSON.parse(JSON.stringify(value)); }
+function sha256(value) { return createHash('sha256').update(value).digest('hex'); }

package/src/tooling/portable/output/deterministic.zip.js

@@ -0,0 +1,88 @@
+import { crc32 as nativeCrc32 } from 'node:zlib';
+
+export function createDeterministicStoredZip(entries = []) {
+  const normalized = entries
+    .map((entry) => ({ name: safeZipPath(entry?.name || ''), data: bytesFrom(entry?.data) }))
+    .filter((entry) => entry.name)
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const duplicate = normalized.find((entry, index) => index > 0 && entry.name === normalized[index - 1].name);
+  if (duplicate) throw new Error(`portable.zip.path.duplicate:${duplicate.name}`);
+
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+  for (const entry of normalized) {
+    const name = Buffer.from(entry.name, 'utf8');
+    const data = Buffer.isBuffer(entry.data) ? entry.data : entry.data instanceof Uint8Array ? Buffer.from(entry.data.buffer, entry.data.byteOffset, entry.data.byteLength) : Buffer.from(entry.data);
+    const crc = crc32(data);
+    const local = Buffer.alloc(30 + name.length);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6);
+    local.writeUInt16LE(0, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(0x0021, 12); // 1980-01-01 for deterministic archives.
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(data.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    name.copy(local, 30);
+    localParts.push(local, data);
+
+    const central = Buffer.alloc(46 + name.length);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(0, 10);
+    central.writeUInt16LE(0, 12);
+    central.writeUInt16LE(0x0021, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(data.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(0, 38);
+    central.writeUInt32LE(offset, 42);
+    name.copy(central, 46);
+    centralParts.push(central);
+    offset += local.length + data.length;
+  }
+  const centralDirectory = Buffer.concat(centralParts);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(normalized.length, 8);
+  end.writeUInt16LE(normalized.length, 10);
+  end.writeUInt32LE(centralDirectory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+  return Buffer.concat([...localParts, centralDirectory, end]);
+}
+
+export function safeZipPath(value = '') {
+  const input = String(value || '').replace(/\\/g, '/').replace(/^\/+/, '');
+  const parts = [];
+  for (const part of input.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') return '';
+    parts.push(part.replace(/[\u0000-\u001f<>:"|?*]/g, '_'));
+  }
+  return parts.join('/');
+}
+
+function bytesFrom(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  return Buffer.from(String(value ?? ''), 'utf8');
+}
+
+function crc32(buffer) {
+  return nativeCrc32(buffer) >>> 0;
+}