@tiinex/core 0.1.1

package/src/tooling/portable/schema/schema.guide.js

@@ -0,0 +1,326 @@
+import { resolveSchemaCapabilities } from '../../../schemas/capability.registry.js';
+import { buildArtifactCreationContract } from '../../../schemas/creation.contracts.js';
+import { schemaRegistry } from '../../../schemas/registry.js';
+import { portableFinding } from '../findings.js';
+import { selectPortableLoadedSchemaMaterial } from '../providers/schema.providers.js';
+import {
+  conditionalContractGroups,
+  conditionalCreationInputs,
+  contractRules,
+  parsePortableSchemaDocument,
+  readPortableSchemaSections
+} from './schema.contract.js';
+import { resolvePortableLlmCompanion } from './llm.companion.js';
+import { compilePortableSchemaContract } from './contract.compile.js';
+
+export const PORTABLE_SCHEMA_GUIDE_SCHEMA_ID = 'tiinex.llm.schema-guide.v1';
+export const PORTABLE_SCHEMA_GUIDE_COMPILER_VERSION = '4';
+
+export function buildPortableSchemaGuide(input = {}, options = {}) {
+  const schemaId = String(input.schemaId || options.schemaId || '').trim();
+  const task = normalizeTask(input.task || options.task || 'read');
+  const detail = normalizeDetail(input.detail || options.detail || 'compact');
+  const schemaSelection = selectPortableLoadedSchemaMaterial(input.materials || input, { schemaId });
+  const schemaMaterial = schemaSelection.material || null;
+  const module = schemaRegistry.byId.get(schemaId) || null;
+  const binding = module?.binding || {};
+  const markdown = schemaMaterial?.markdown || '';
+  const document = markdown ? parsePortableSchemaDocument(markdown) : null;
+  const compiledContract = document ? compilePortableSchemaContract(document) : null;
+  const capabilityName = capabilityForTask(task);
+  const resolution = resolveSchemaCapabilities({ schemaId }, { capability: capabilityName });
+  const creationContract = task === 'create' || task === 'continue' ? buildArtifactCreationContract({ schemaId, transitionType: task === 'continue' ? 'continue' : 'create-artifact' }) : null;
+  const companionResult = resolvePortableLlmCompanion({ schemaId, task, module, input, options });
+  const companion = companionResult.companion;
+  const exactReadableContract = Boolean(
+    schemaMaterial?.markdown
+    && document?.schemaId === schemaId
+    && schemaMaterial.qualification?.exactSchemaIdentity === true
+    && schemaMaterial.qualification?.sourceQualified === true
+    && schemaMaterial.qualification?.representationIntegrity === 'verified'
+  );
+  const creationRequested = task === 'create' || task === 'continue';
+  const requiredSections = compiledContract ? uniqueStrings([
+    ...compiledContract.validation.requiredSections,
+    ...(creationRequested ? compiledContract.creation.requiredSections : [])
+  ]) : [];
+  const requiredFields = compiledContract ? [...compiledContract.validation.requiredFields] : [];
+  const optionalSections = detail === 'compact' ? [] : compiledContract ? [...compiledContract.validation.optionalSections] : [];
+  const optionalFields = detail === 'full' ? (compiledContract ? [...compiledContract.validation.optionalFields] : []) : [];
+  const conditionalRequirements = document ? buildConditionalRequirements(document) : [];
+  const rules = document ? contractRules(document.validation) : [];
+  const creationRules = document ? contractRules(document.creation) : [];
+  const requiredInputs = creationRequested ? uniqueStrings([
+    ...(creationContract?.inputs?.required || []),
+    ...(compiledContract ? compiledContract.creation.requiredInputs : []),
+    ...requiredFields
+  ]) : [];
+  const optionalInputs = creationRequested && compiledContract ? [...compiledContract.creation.optionalInputs] : [];
+  const toolingConfiguration = creationRequested && compiledContract ? [...compiledContract.creation.toolingConfigurationFields] : [];
+  const hardRules = prioritizeRules([...rules, ...creationRules], task, detail);
+  const purpose = companion.purpose || document?.summary || module?.label || `Work with ${schemaId || 'an unknown Tiinex schema'}.`;
+  const findings = [...schemaSelection.findings, ...companionResult.findings];
+  if (!schemaId) findings.push(portableFinding('error', 'portable.schema-guide.schema.required', 'Schema guide generation requires a schema id.'));
+  if (!schemaMaterial && !module) findings.push(portableFinding('error', 'portable.schema-guide.schema.unavailable', 'Neither readable schema material nor a registered schema module is available.', { schemaId }));
+  if (!schemaMaterial) findings.push(portableFinding('info', 'portable.schema-guide.readable-schema.unavailable', 'The guide is limited to registered runtime metadata because readable schema Markdown was not supplied.', { schemaId }));
+  if (schemaMaterial && document?.schemaId && document.schemaId !== schemaId) findings.push(portableFinding('error', 'portable.schema-guide.readable-schema.mismatch', 'Supplied readable schema material declares a different Current Schema than the requested schema.', {
+    requestedSchemaId: schemaId,
+    declaredSchemaId: document.schemaId,
+    ref: schemaMaterial.path
+  }));
+  if (!companion.available) findings.push(portableFinding('info', 'portable.schema-guide.llm-companion.generic', 'No schema-specific LLM companion hints were registered; the guide was compiled generically from schema contracts and runtime capabilities.', { schemaId }));
+  const cacheBasis = binding.checksum?.value || binding.checksum || schemaMaterial?.markdown || `${schemaId}:${module?.id || ''}`;
+  const guide = Object.freeze({
+    schema: PORTABLE_SCHEMA_GUIDE_SCHEMA_ID,
+    schemaId,
+    task,
+    detail,
+    cacheKey: guideCacheKey({ schemaId, task, detail, basis: cacheBasis, companionVersion: companion.version }),
+    cacheBasis: Object.freeze({
+      schemaChecksum: binding.checksum?.value || binding.checksum || '',
+      sourceCommit: binding.sourceCommit || '',
+      compilerVersion: PORTABLE_SCHEMA_GUIDE_COMPILER_VERSION,
+      companionVersion: companion.version,
+      companionSource: companion.source
+    }),
+    purpose,
+    parentSchemaId: document?.parentSchemaId || module?.parentSchemaId || '',
+    capability: Object.freeze({
+      requested: capabilityName,
+      exactModule: Boolean(resolution.descriptor?.moduleId === schemaId && !resolution.fallbackUsed),
+      status: exactReadableContract ? 'readable-exact-contract' : (resolution.capability?.status || ''),
+      resolvedThrough: exactReadableContract ? schemaId : (resolution.descriptor?.moduleId || 'tiinex.root.v1'),
+      fallbackUsed: exactReadableContract ? false : Boolean(resolution.fallbackUsed),
+      runtimeStatus: resolution.capability?.status || '',
+      runtimeResolvedThrough: resolution.descriptor?.moduleId || 'tiinex.root.v1',
+      runtimeFallbackUsed: Boolean(resolution.fallbackUsed)
+    }),
+    factoryDescriptor: resolution.descriptor?.factory || null,
+    requiredInputs: Object.freeze(limitList(requiredInputs, detail === 'compact' ? 18 : 80)),
+    requiredStructure: Object.freeze(limitList(requiredSections, detail === 'compact' ? 14 : 80)),
+    requiredFields: Object.freeze(limitList(requiredFields, detail === 'compact' ? 24 : 120)),
+    declarationContracts: Object.freeze((compiledContract?.declarations || []).map((contract) => Object.freeze({
+      group: contract.group,
+      targetHeadings: contract.targetHeadings,
+      requiredFields: contract.requiredFields,
+      optionalFields: detail === 'compact' ? Object.freeze([]) : contract.optionalFields,
+      allowLiteralNone: contract.allowLiteralNone
+    }))),
+    optionalInputs: Object.freeze(limitList(optionalInputs, detail === 'compact' ? 18 : 80)),
+    toolingConfiguration: Object.freeze({
+      fields: Object.freeze(limitList(toolingConfiguration, detail === 'compact' ? 18 : 80)),
+      authoringInputs: false,
+      statement: 'Create-surface prompt configuration is tooling metadata, not artifact content.'
+    }),
+    conditionalRequirements: Object.freeze(conditionalRequirements.slice(0, detail === 'compact' ? 12 : 80)),
+    optionalStructure: Object.freeze(optionalSections),
+    optionalFields: Object.freeze(optionalFields),
+    authoringSteps: Object.freeze(companion.authoringSteps.length ? companion.authoringSteps : defaultAuthoringSteps({ task, schemaId, requiredSections, requiredFields })),
+    hardRules: Object.freeze(limitList([...companion.hardRules, ...hardRules], detail === 'compact' ? 18 : 80)),
+    questions: Object.freeze(limitList(companion.questions, detail === 'compact' ? 10 : 40)),
+    commonFailures: Object.freeze(limitList(companion.commonFailures, detail === 'compact' ? 10 : 40)),
+    companion: Object.freeze({
+      available: companion.available,
+      source: companion.source,
+      version: companion.version,
+      prioritySections: companion.prioritySections
+    }),
+    validationPlan: Object.freeze(validationPlan({ schemaId, resolution, document, task })),
+    retrieval: Object.freeze({
+      recommendedNext: recommendedRetrieval({ task, detail, document, creationContract, companion }),
+      availableSections: Object.freeze((document?.outline || []).map((section) => section.title)),
+      fullSchemaAvailable: Boolean(schemaMaterial)
+    }),
+    authority: Object.freeze({
+      readableSchemaAvailable: Boolean(schemaMaterial),
+      exactReadableContract,
+      schemaPath: schemaMaterial?.path || binding.snapshot || '',
+      sourcePath: schemaMaterial?.source?.path || binding.sourcePath || '',
+      sourceRepository: schemaMaterial?.source?.repository || binding.sourceRepository || '',
+      sourceCommit: schemaMaterial?.source?.commit || binding.sourceCommit || '',
+      materialQualification: schemaMaterial?.qualification ? Object.freeze({
+        authority: schemaMaterial.qualification.authority,
+        sourceQualified: schemaMaterial.qualification.sourceQualified,
+        representationIntegrity: schemaMaterial.qualification.representationIntegrity,
+        runtimeBootstrapProvenance: schemaMaterial.qualification.runtimeBootstrapProvenance,
+        registered: schemaMaterial.qualification.registered
+      }) : null,
+      statement: schemaMaterial ? `resolved readable schema material (${schemaMaterial.qualification?.authority || 'unqualified'})` : 'Registered runtime metadata only; obtain readable canonical schema for prose-bound semantics.'
+    })
+  });
+  return Object.freeze({ guide, findings: Object.freeze(findings) });
+}
+
+export function readPortableSchemaGuideSections(input = {}, options = {}) {
+  const schemaId = String(input.schemaId || options.schemaId || '').trim();
+  const schemaSelection = selectPortableLoadedSchemaMaterial(input.materials || input, { schemaId });
+  const schemaMaterial = schemaSelection.material || null;
+  if (!schemaMaterial) return Object.freeze({
+    schema: 'tiinex.portable.schema-section.result.v1',
+    schemaId,
+    selectors: Object.freeze([]),
+    matches: Object.freeze([]),
+    truncated: false,
+    findings: Object.freeze([portableFinding('error', 'portable.schema-section.schema.unavailable', 'Readable schema material is required to read schema sections.', { schemaId })])
+  });
+  const selectors = input.sections || input.section || options.sections || options.section || [];
+  const result = readPortableSchemaSections(schemaMaterial.markdown, selectors, options);
+  return Object.freeze({ ...result, findings: Object.freeze(schemaSelection.findings), authority: schemaMaterial.qualification?.authority || '', path: schemaMaterial.path });
+}
+
+export function planPortableArtifact(input = {}, options = {}) {
+  const guideResult = buildPortableSchemaGuide({ ...input, task: input.task || 'create' }, options);
+  const guide = guideResult.guide;
+  const provided = normalizeProvidedInputs(input.inputs || input.values || {});
+  const missingInputs = guide.requiredInputs.filter((name) => !provided.has(normalizeKey(name)));
+  const plan = Object.freeze({
+    schema: 'tiinex.llm.artifact-plan.v1',
+    schemaId: guide.schemaId,
+    task: guide.task,
+    cacheKey: guide.cacheKey,
+    readyToDraft: missingInputs.length === 0 && guide.authority.readableSchemaAvailable && !guideResult.findings.some((finding) => finding.severity === 'error'),
+    conditionReviewRequired: guide.conditionalRequirements.length > 0,
+    missingInputs: Object.freeze(missingInputs),
+    providedInputs: Object.freeze([...provided.values()]),
+    structure: Object.freeze(guide.requiredStructure.map((section, index) => Object.freeze({ order: index + 1, section }))),
+    requiredFields: guide.requiredFields,
+    authoringSteps: guide.authoringSteps,
+    validationPlan: guide.validationPlan,
+    conditionalRequirements: guide.conditionalRequirements,
+    retrieval: guide.retrieval,
+    limitations: Object.freeze([
+      ...(guide.authority.readableSchemaAvailable ? [] : ['Readable schema material is unavailable.']),
+      ...(guide.capability.fallbackUsed ? ['Runtime capability resolution used fallback.'] : []),
+      ...(guide.conditionalRequirements.length ? ['Conditional requirements require trigger-aware review before the draft can be qualified.'] : [])
+    ])
+  });
+  const findings = [...guideResult.findings];
+  if (missingInputs.length) findings.push(portableFinding('warning', 'portable.artifact-plan.inputs.missing', 'Required authoring inputs are missing.', { schemaId: guide.schemaId, missingInputs }));
+  return Object.freeze({ plan, guide, findings: Object.freeze(findings) });
+}
+
+function validationPlan({ resolution = {}, document = null, task = 'read' }) {
+  const steps = ['Parse continuity envelope and declared schema identity.'];
+  if (document) steps.push('Apply structured requirements compiled from the supplied readable schema contract.');
+  if (resolution.capability?.status === 'implemented' && !resolution.fallbackUsed) steps.push(`Run exact registered ${capabilityForTask(task)} capability.`);
+  else steps.push('Run available Root/runtime checks and report partial qualification explicitly.');
+  if (task === 'create' || task === 'continue') steps.push('Validate the completed local draft before staging or export.');
+  return steps;
+}
+
+function recommendedRetrieval({ task, detail, document, creationContract, companion }) {
+  const next = [];
+  if (!document) next.push('supply-readable-schema');
+  next.push(...(companion?.prioritySections || []).map((section) => `read:${section}`));
+  next.push(...(companion?.retrievalHints || []));
+  if (task === 'create' || task === 'continue') {
+    if (creationContract?.status !== 'ready') next.push('read:Artifact Creation Contract');
+    next.push('read:Minimal Example');
+  }
+  if (detail === 'compact') next.push('read:relevant-validation-groups-on-demand');
+  return Object.freeze(uniqueStrings(next));
+}
+
+function buildConditionalRequirements(document = {}) {
+  const validation = conditionalContractGroups(document.validation).map((entry) => Object.freeze({
+    source: 'validation-contract',
+    group: entry.name,
+    requiredWhen: entry.requiredWhen,
+    requiredSections: entry.requiredSections,
+    requiredFields: entry.requiredFields
+  }));
+  const creation = conditionalCreationInputs(document).map((entry) => Object.freeze({
+    source: 'creation-contract',
+    group: entry.group,
+    requiredWhen: entry.requiredWhen,
+    requiredSections: Object.freeze([]),
+    requiredFields: entry.fields
+  }));
+  return Object.freeze([...validation, ...creation]);
+}
+
+function prioritizeRules(rules = [], task = 'read', detail = 'compact') {
+  const normalized = uniqueStrings(rules);
+  const scored = normalized.map((rule) => ({
+    rule,
+    score: (/\b(must|must not|required|never|do not|should not)\b/i.test(rule) ? 4 : 0)
+      + (task === 'create' && /\b(create|generated|artifact|field|section)\b/i.test(rule) ? 2 : 0)
+      + (/\b(provenance|parent|origin|boundary|evidence|truth|authority)\b/i.test(rule) ? 1 : 0)
+  }));
+  scored.sort((a, b) => b.score - a.score || a.rule.localeCompare(b.rule));
+  return scored.slice(0, detail === 'compact' ? 16 : 80).map((item) => item.rule);
+}
+
+function defaultAuthoringSteps({ task, schemaId, requiredSections, requiredFields }) {
+  if (task === 'read') return [
+    `Confirm the declared schema is ${schemaId || 'the requested schema'}.`,
+    'Read continuity, parent, origin, boundaries, and qualification before interpreting body meaning.',
+    'Retrieve only the schema sections needed for the current question.'
+  ];
+  return [
+    'Establish the real continuity parent and origin boundary.',
+    ...(requiredSections.length ? ['Create the required body sections in schema order.'] : []),
+    ...(requiredFields.length ? ['Collect every required field before claiming the draft is ready.'] : []),
+    'Write a local draft without inheriting or guessing source provenance.',
+    'Validate the draft and repair only reported findings.'
+  ];
+}
+
+function guideCacheKey({ schemaId, task, detail, basis, companionVersion }) {
+  return [schemaId || 'unknown', task, detail, `schema-${stableHash(basis)}`, `compiler-${PORTABLE_SCHEMA_GUIDE_COMPILER_VERSION}`, `companion-${companionVersion || 'generic'}`].join(':');
+}
+
+function stableHash(value = '') {
+  const text = String(value || '');
+  let hash = 2166136261;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+function normalizeProvidedInputs(values = {}) {
+  const map = new Map();
+  if (Array.isArray(values)) {
+    for (const value of values) {
+      const name = typeof value === 'string' ? value : value?.name || value?.field || '';
+      if (name) map.set(normalizeKey(name), String(name));
+    }
+    return map;
+  }
+  for (const [name, value] of Object.entries(values || {})) {
+    if (value === undefined || value === null || value === '') continue;
+    map.set(normalizeKey(name), name);
+  }
+  return map;
+}
+
+function capabilityForTask(task = 'read') {
+  if (task === 'create') return 'create';
+  if (task === 'continue') return 'continue';
+  if (task === 'validate') return 'validate';
+  return 'read';
+}
+
+function normalizeTask(value = '') {
+  const task = String(value || '').toLowerCase().trim();
+  return ['read', 'create', 'continue', 'validate', 'repair'].includes(task) ? task : 'read';
+}
+
+function normalizeDetail(value = '') {
+  const detail = String(value || '').toLowerCase().trim();
+  return ['compact', 'standard', 'full'].includes(detail) ? detail : 'compact';
+}
+
+function normalizeKey(value = '') {
+  return String(value || '').toLowerCase().replace(/[`*_#]/g, '').replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function limitList(values = [], max = 20) {
+  return uniqueStrings(values).slice(0, max);
+}
+
+function uniqueStrings(values = []) {
+  return [...new Set((Array.isArray(values) ? values : []).map((value) => String(value || '').trim()).filter(Boolean))];
+}

package/src/tooling/portable/schema/schema.snapshot.js

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto';
+import { parsePortableSchemaDocument } from './schema.contract.js';
+import { projectMachineShapeSemanticIdentity } from './contract.machine-shape.js';
+
+export const PORTABLE_SCHEMA_FRESHNESS_SCHEMA_ID = 'tiinex.portable.schema-freshness.v1';
+
+export function comparePortableSchemaSnapshots(input = {}) {
+  const candidate = normalizeSide(input.candidate || input.bundled || {});
+  const reference = normalizeSide(input.reference || input.canonical || {});
+  if (!candidate.markdown || !reference.markdown) return result('comparison-unresolved', candidate, reference, ['Both candidate and reference schema Markdown must be supplied explicitly.']);
+  const candidateDoc = parsePortableSchemaDocument(candidate.markdown);
+  const referenceDoc = parsePortableSchemaDocument(reference.markdown);
+  if (!candidateDoc.schemaId || !referenceDoc.schemaId) return result('comparison-unresolved', candidate, reference, ['Schema identity could not be parsed from one or both supplied materials.']);
+  if (candidateDoc.schemaId !== referenceDoc.schemaId) return result('authority-mismatch', candidate, reference, [`Schema identity differs: ${candidateDoc.schemaId} != ${referenceDoc.schemaId}.`], candidateDoc, referenceDoc);
+  if (input.expectedReferenceAuthority) {
+    const mismatch = authorityMismatch(reference.authority, input.expectedReferenceAuthority);
+    if (mismatch.length) return result('authority-mismatch', candidate, reference, mismatch, candidateDoc, referenceDoc);
+  }
+  const candidateShape = contractShape(candidateDoc);
+  const referenceShape = contractShape(referenceDoc);
+  const candidateFingerprint = fingerprint(candidateShape);
+  const referenceFingerprint = fingerprint(referenceShape);
+  const status = candidateFingerprint === referenceFingerprint ? 'equivalent-current' : 'materially-stale';
+  return Object.freeze({
+    schema: PORTABLE_SCHEMA_FRESHNESS_SCHEMA_ID,
+    status,
+    schemaId: referenceDoc.schemaId,
+    candidate: Object.freeze({ authority: candidate.authority, fingerprint: candidateFingerprint }),
+    reference: Object.freeze({ authority: reference.authority, fingerprint: referenceFingerprint }),
+    differences: Object.freeze(status === 'materially-stale' ? diffShapes(candidateShape, referenceShape) : [])
+  });
+}
+
+function normalizeSide(value) {
+  return Object.freeze({ markdown: String(value.markdown || value.content || ''), authority: Object.freeze({ ...(value.authority || value.source || {}) }) });
+}
+
+function contractShape(document) {
+  return Object.freeze({
+    schemaId: document.schemaId,
+    parentSchemaId: document.parentSchemaId || '',
+    envelopeSchemaId: document.envelopeSchemaId || '',
+    validation: normalizeContract(document.validation, { suppressValidationMachineShapes: true }),
+    creation: normalizeContract(document.creation),
+    machineShapes: projectMachineShapeSemanticIdentity(document)
+  });
+}
+
+function normalizeContract(contract = {}, options = {}) {
+  const suppressValidationMachineShapes = options.suppressValidationMachineShapes === true;
+  return (contract.groups || []).map((group) => ({
+    name: group.name,
+    categories: (group.categories || []).filter((category) => !(suppressValidationMachineShapes && String(category.name || '').trim() === 'Machine Shape Definitions')).map((category) => ({
+      name: category.name,
+      nodes: canonicalCategoryNodes(category)
+    }))
+  }));
+}
+
+function canonicalCategoryNodes(category = {}) {
+  const ordered = String(category.name || '').trim() === 'Ordering';
+  const nodes = (category.nodes || []).map((node) => canonicalNode(node, ordered));
+  if (nodes.length) return ordered ? nodes : nodes.sort(compareCanonicalNodes);
+  const fallback = [...(category.items || [])].map((value) => ({ value: String(value), children: [] }));
+  return ordered ? fallback : fallback.sort(compareCanonicalNodes);
+}
+
+function canonicalNode(node = {}, ordered = false) {
+  const children = (node.children || []).map((child) => canonicalNode(child, ordered));
+  if (!ordered) children.sort(compareCanonicalNodes);
+  return { value: String(node.value || ''), children };
+}
+
+function compareCanonicalNodes(left = {}, right = {}) {
+  return compareExactStrings(JSON.stringify(left), JSON.stringify(right));
+}
+
+function compareExactStrings(left = '', right = '') {
+  const a = String(left);
+  const b = String(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+
+function fingerprint(value) {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+function diffShapes(candidate, reference) {
+  const diffs = [];
+  if ((candidate.parentSchemaId || '') !== (reference.parentSchemaId || '')) diffs.push(`parent schema identity differs: ${candidate.parentSchemaId || '(none)'} != ${reference.parentSchemaId || '(none)'}`);
+  if ((candidate.envelopeSchemaId || '') !== (reference.envelopeSchemaId || '')) diffs.push(`envelope schema identity differs: ${candidate.envelopeSchemaId || '(none)'} != ${reference.envelopeSchemaId || '(none)'}`);
+  for (const surface of ['validation', 'creation']) {
+    const a = JSON.stringify(candidate[surface]);
+    const b = JSON.stringify(reference[surface]);
+    if (a !== b) diffs.push(`${surface} contract differs`);
+  }
+  if (JSON.stringify(candidate.machineShapes) !== JSON.stringify(reference.machineShapes)) diffs.push('machine-shape authority differs');
+  return diffs;
+}
+
+function authorityMismatch(actual = {}, expected = {}) {
+  const diffs = [];
+  for (const key of ['repository', 'commit', 'path']) {
+    if (expected[key] && actual[key] !== expected[key]) diffs.push(`Reference authority ${key} mismatch.`);
+  }
+  return diffs;
+}
+
+function result(status, candidate, reference, differences, candidateDoc = null, referenceDoc = null) {
+  return Object.freeze({
+    schema: PORTABLE_SCHEMA_FRESHNESS_SCHEMA_ID,
+    status,
+    schemaId: referenceDoc?.schemaId || candidateDoc?.schemaId || '',
+    candidate: Object.freeze({ authority: candidate.authority, fingerprint: '' }),
+    reference: Object.freeze({ authority: reference.authority, fingerprint: '' }),
+    differences: Object.freeze(differences)
+  });
+}

package/src/tooling/portable/session/portable.session.js

@@ -0,0 +1,145 @@
+import {
+  auditPortableMaterial,
+  createPortableArtifactDraft,
+  discoverPortableTooling,
+  compilePortableSchemaGuide,
+  explainPortableArtifactFindings,
+  describePortableSchemaChain,
+  inspectPortableAssetIndex,
+  inspectPortableCreationContract,
+  inspectPortableMaterial,
+  planPortableArtifactCreation,
+  planPortableArtifactRepairs,
+  preparePortableTaskOperation,
+  preparePortableAssetAnalysisOperation,
+  readPortableSchemaSection,
+  listPortableProviders,
+  makePortableWriterBrief,
+  resolvePortableCapabilities,
+  resolvePortableSchemaChainMaterialOperation,
+  resolvePortableSchemaMaterialOperation,
+  searchPortableLineage,
+  stagePortableArtifactDraft,
+  resolvePortableLineage,
+  validatePortableArtifactDraft
+} from '../engine.facade.js';
+import { buildPortableRuntimePackage, inspectPortableRuntimePackage, rehydratePortableRuntimePackage, roundTripPortableRuntimePackage } from '../package/runtime.package.js';
+
+export const PORTABLE_SESSION_SCHEMA_ID = 'tiinex.portable.session.v1';
+
+export function openPortableSession(input = {}) {
+  const state = normalizeSessionState(input);
+  return Object.freeze({
+    schema: PORTABLE_SESSION_SCHEMA_ID,
+    prepareTask: (request = {}, options = {}) => preparePortableTaskOperation({ ...state.materials, ...request, schemaCache: state.schemaCache }, options),
+    discoverTooling: (request = {}, options = {}) => discoverPortableTooling({ ...request, schemaCache: state.schemaCache }, options),
+    listProviders: (request = {}, options = {}) => listPortableProviders({ ...state.materials, ...request, schemaCache: state.schemaCache }, options),
+    resolveSchemaMaterial: (request = {}, options = {}) => resolvePortableSchemaMaterialOperation({ ...state.materials, ...request, schemaCache: state.schemaCache }, options),
+    resolveSchemaChainMaterial: (request = {}, options = {}) => resolvePortableSchemaChainMaterialOperation({ ...state.materials, ...request, schemaCache: state.schemaCache }, options),
+    inspect: (options = {}) => inspectPortableMaterial(state.materials, options),
+    audit: (options = {}) => auditPortableMaterial(state.materials, options),
+    resolveLineage: (options = {}) => resolvePortableLineage(state.materials, { ...options, startId: options.startId || state.currentFocus }),
+    resolveCapabilities: (request = {}, options = {}) => resolvePortableCapabilities(request, options),
+    describeSchemaChain: (request = {}, options = {}) => describePortableSchemaChain({ ...state.materials, ...request }, options),
+    inspectCreationContract: (request = {}, options = {}) => inspectPortableCreationContract(request, options),
+    makeWriterBrief: (request = {}, options = {}) => makePortableWriterBrief({ ...state.materials, ...request }, options),
+    schemaGuide: (request = {}, options = {}) => compilePortableSchemaGuide({ ...state.materials, ...request }, options),
+    readSchemaSection: (request = {}, options = {}) => readPortableSchemaSection({ ...state.materials, ...request }, options),
+    planArtifact: (request = {}, options = {}) => planPortableArtifactCreation({ ...state.materials, ...request }, options),
+    createLocalDraft: (request = {}, options = {}) => createPortableArtifactDraft({ ...state.materials, ...request }, options),
+    validateDraft: (request = {}, options = {}) => validatePortableArtifactDraft({ ...state.materials, ...request }, options),
+    stageDraft: (request = {}, options = {}) => stagePortableArtifactDraft({ ...state.materials, ...request }, options),
+    explainFindings: (request = {}, options = {}) => explainPortableArtifactFindings(request, options),
+    repairPlan: (request = {}, options = {}) => planPortableArtifactRepairs(request, options),
+    searchLineage: (request = {}, options = {}) => searchPortableLineage({ ...state.materials, ...request }, options),
+    inspectAssets: (request = {}, options = {}) => inspectPortableAssetIndex({ ...state.materials, ...request }, options),
+    prepareAssetAnalysis: (request = {}, options = {}) => preparePortableAssetAnalysisOperation({ ...state.materials, ...request }, options),
+    planDurableMaterialization: async (request = {}) => {
+      const { planPortableDurableMaterialization } = await import('../materialization/durable.materialize.js');
+      return planPortableDurableMaterialization({ session: state, ...request });
+    },
+    materializeDurableFindings: async (request = {}, options = {}) => {
+      const { materializePortableDurableFindings } = await import('../materialization/durable.materialize.js');
+      return materializePortableDurableFindings({ session: state, ...request }, options);
+    },
+    createCheckpoint: async (request = {}, options = {}) => {
+      const { createPortableCheckpoint } = await import('../checkpoint/portable.checkpoint.js');
+      return createPortableCheckpoint({ session: state, ...request }, options);
+    },
+    buildRuntimePackage: (request = {}, options = {}) => buildPortableRuntimePackage({ session: state, ...request }, options),
+    inspectRuntimePackage: (request = {}) => inspectPortableRuntimePackage(request),
+    rehydrateRuntimePackage: (request = {}) => rehydratePortableRuntimePackage(request),
+    roundTripRuntimePackage: (request = {}, options = {}) => roundTripPortableRuntimePackage({ session: state, ...request }, options),
+    snapshot: () => serializePortableSession(state),
+    withFocus: (currentFocus = '') => openPortableSession({ ...state, currentFocus }),
+    withDurableFinding: (finding = {}) => openPortableSession({ ...state, durableFindings: [...state.durableFindings, finding] }),
+    withStagedArtifact: (artifact = {}) => openPortableSession({ ...state, stagedArtifacts: [...state.stagedArtifacts, artifact] }),
+    withSchemaCache: (entries = []) => openPortableSession({ ...state, schemaCache: mergeSchemaCache(state.schemaCache, entries) }),
+    withCheckpoint: (lastCheckpoint = {}) => openPortableSession({ ...state, lastCheckpoint })
+  });
+}
+
+export function serializePortableSession(sessionOrState = {}) {
+  const source = typeof sessionOrState.snapshot === 'function' ? sessionOrState.snapshot() : normalizeSessionState(sessionOrState);
+  return Object.freeze(JSON.parse(JSON.stringify(source)));
+}
+
+export function restorePortableSession(snapshot = {}) {
+  if (snapshot?.schema !== PORTABLE_SESSION_SCHEMA_ID) throw new Error('portable.session.schema.invalid');
+  const version = Number(snapshot?.version || 0);
+  if (![1, 2].includes(version)) throw new Error('portable.session.version.unsupported');
+  return openPortableSession(version === 1 ? { ...snapshot, version: 2, schemaCache: [] } : snapshot);
+}
+
+function normalizeSessionState(input = {}) {
+  const materials = input.materials || pickMaterialInput(input);
+  return Object.freeze({
+    schema: PORTABLE_SESSION_SCHEMA_ID,
+    version: 2,
+    boundary: Object.freeze({
+      hiddenConversationStateIsProvenance: false,
+      remoteFetch: 'explicit-host-mediated-only',
+      remoteWrite: false,
+      sourceMutation: false
+    }),
+    materials: Object.freeze({
+      markdown: typeof materials.markdown === 'string' ? materials.markdown : undefined,
+      path: materials.path || undefined,
+      files: Object.freeze((materials.files || []).map((file) => Object.freeze({ ...file }))),
+      records: Object.freeze((materials.records || []).map((record) => Object.freeze({ ...record }))),
+      assets: Object.freeze((materials.assets || []).map((asset) => Object.freeze({ ...asset }))),
+      findings: Object.freeze((materials.findings || []).map((finding) => Object.freeze({ ...finding }))),
+      sourceMode: materials.sourceMode || 'portable-local'
+    }),
+    currentFocus: String(input.currentFocus || ''),
+    stagedArtifacts: Object.freeze((input.stagedArtifacts || []).map((artifact) => Object.freeze({ ...artifact }))),
+    durableFindings: Object.freeze((input.durableFindings || []).map((finding) => Object.freeze({ ...finding }))),
+    lastCheckpoint: input.lastCheckpoint ? Object.freeze({ ...input.lastCheckpoint }) : null,
+    qualification: input.qualification ? Object.freeze({ ...input.qualification }) : null,
+    schemaCache: Object.freeze(normalizeSchemaCache(input.schemaCache))
+  });
+}
+
+function pickMaterialInput(input = {}) {
+  return {
+    markdown: input.markdown,
+    path: input.path,
+    files: input.files || [],
+    records: input.records || [],
+    assets: input.assets || [],
+    findings: input.findings || [],
+    sourceMode: input.sourceMode
+  };
+}
+
+
+function normalizeSchemaCache(value) {
+  const entries = value instanceof Map ? [...value.values()] : Array.isArray(value) ? value : value && typeof value === 'object' ? Object.values(value) : [];
+  return entries.filter((entry) => entry?.schemaId && typeof entry?.markdown === 'string').map((entry) => Object.freeze({ ...entry }));
+}
+
+function mergeSchemaCache(current, next) {
+  const map = new Map(normalizeSchemaCache(current).map((entry) => [entry.cacheKey || `${entry.schemaId}:${entry.path}`, entry]));
+  for (const entry of normalizeSchemaCache(next)) map.set(entry.cacheKey || `${entry.schemaId}:${entry.path}`, entry);
+  return [...map.values()];
+}