@tiinex/core 0.1.1

package/src/tooling/portable/materialization/durable.materialize.js

@@ -0,0 +1,162 @@
+import { createPortableLocalDraft, stagePortableDraft } from '../draft/draft.create.js';
+import { portableFinding, summarizePortableFindings } from '../findings.js';
+import { resolvePortableSchemaChainMaterial } from '../providers/schema.providers.js';
+import { openPortableSession } from '../session/portable.session.js';
+
+export const PORTABLE_DURABLE_MATERIALIZATION_PLAN_SCHEMA_ID = 'tiinex.portable.durable-materialization.plan.v1';
+export const PORTABLE_DURABLE_MATERIALIZATION_RESULT_SCHEMA_ID = 'tiinex.portable.durable-materialization.result.v1';
+
+export function planPortableDurableMaterialization(input = {}) {
+  const durableFindings = normalizeFindings(input.durableFindings || input.session?.durableFindings || input.snapshot?.durableFindings || []);
+  const specs = normalizeSpecs(input.materializations || input.specs || []);
+  const findings = [];
+  const knownIds = new Set(durableFindings.map(findingId));
+  const assigned = new Set();
+  for (const spec of specs) {
+    if (!spec.schemaId) findings.push(portableFinding('error', 'portable.materialization.schema.required', 'Each durable materialization requires an explicit target schema id; portable tooling will not guess artifact type.', { materializationId: spec.id }));
+    if (!spec.findingIds.length) findings.push(portableFinding('warning', 'portable.materialization.findings.empty', 'A materialization spec references no durable findings.', { materializationId: spec.id }));
+    for (const id of spec.findingIds) {
+      if (!knownIds.has(id)) findings.push(portableFinding('error', 'portable.materialization.finding.unknown', 'A materialization spec references an unknown durable finding.', { materializationId: spec.id, findingId: id }));
+      else if (assigned.has(id)) findings.push(portableFinding('error', 'portable.materialization.finding.duplicate', 'A durable finding is assigned to more than one materialization in the same operation.', { findingId: id }));
+      else assigned.add(id);
+    }
+  }
+  const unassigned = durableFindings.filter((finding) => !assigned.has(findingId(finding)));
+  if (unassigned.length) findings.push(portableFinding('info', 'portable.materialization.findings.unassigned', 'Some durable findings remain explicit session state and will not be silently materialized.', { count: unassigned.length }));
+  const findingSummary = summarizePortableFindings(findings);
+  return Object.freeze({
+    schema: PORTABLE_DURABLE_MATERIALIZATION_PLAN_SCHEMA_ID,
+    status: findingSummary.counts.error ? 'blocked' : specs.length ? 'ready' : durableFindings.length ? 'mapping-required' : 'empty',
+    durableFindings: Object.freeze(durableFindings),
+    materializations: Object.freeze(specs.map((spec) => Object.freeze({
+      ...spec,
+      selectedFindings: Object.freeze(durableFindings.filter((finding) => spec.findingIds.includes(findingId(finding))))
+    }))),
+    unassignedFindings: Object.freeze(unassigned),
+    boundary: Object.freeze({ schemaSelectionMustBeExplicit: true, remoteWrite: false, sourceMutation: false }),
+    findings: Object.freeze(findings),
+    findingSummary
+  });
+}
+
+export async function materializePortableDurableFindings(input = {}, options = {}) {
+  const plan = planPortableDurableMaterialization(input);
+  const findings = [...plan.findings];
+  if (plan.status === 'blocked') return result('blocked', plan, [], input, findings);
+  const created = [];
+  for (const item of plan.materializations) {
+    const chain = await resolvePortableSchemaChainMaterial({ ...input, schemaId: item.schemaId }, options);
+    findings.push(...(chain.findings || []));
+    if (chain.status === 'provider-action-required') {
+      created.push(Object.freeze({ id: item.id, status: 'provider-action-required', schemaId: item.schemaId, providerRequest: chain.providerRequest, findingIds: item.findingIds }));
+      continue;
+    }
+    const files = mergeFiles(input.files || input.session?.materials?.files || [], chain.materials?.files || []);
+    const draftResult = createPortableLocalDraft({
+      ...input,
+      ...item,
+      files,
+      schemaId: item.schemaId,
+      values: item.values,
+      sections: item.sections,
+      bodyMarkdown: item.bodyMarkdown,
+      title: item.title,
+      summary: item.summary,
+      path: item.path,
+      parent: item.parent,
+      allowIncomplete: item.allowIncomplete
+    }, options);
+    findings.push(...dedupeNewFindings(findings, draftResult.findings || []));
+    let stageResult = null;
+    const unresolvedSchemaLocator = (draftResult.validation?.findings || []).some((finding) => finding.code === 'schema.reference.locator.unresolved');
+    if (unresolvedSchemaLocator) findings.push(portableFinding('error', 'portable.materialization.schema-reference.locator-unresolved', 'Durable materialization retained a readable local draft but will not stage it while a declared schema representation locator remains unresolved.', { materializationId: item.id, schemaId: item.schemaId }));
+    if (draftResult.draft && item.stage !== false && !unresolvedSchemaLocator) {
+      stageResult = stagePortableDraft({
+        draft: draftResult.draft,
+        validation: draftResult.validation,
+        files,
+        schemaId: item.schemaId,
+        allowInvalid: item.allowInvalid
+      }, options);
+      findings.push(...dedupeNewFindings(findings, stageResult.findings || []));
+    }
+    created.push(Object.freeze({
+      id: item.id,
+      schemaId: item.schemaId,
+      findingIds: item.findingIds,
+      status: stageResult?.status === 'staged' ? 'materialized-and-staged' : draftResult.status,
+      schemaChain: chain,
+      draft: draftResult.draft,
+      validation: draftResult.validation,
+      stagedArtifact: stageResult?.stagedArtifact || null,
+      qualification: draftResult.qualification
+    }));
+  }
+  const successfulIds = new Set(created.filter((item) => item.draft && (!item.stagedArtifact ? item.status !== 'blocked' : true)).flatMap((item) => item.findingIds));
+  const remaining = plan.durableFindings.filter((finding) => !successfulIds.has(findingId(finding)));
+  const status = created.some((item) => item.status === 'provider-action-required') ? 'provider-action-required'
+    : findings.some((finding) => finding.severity === 'error') ? 'degraded'
+      : remaining.length ? 'partial' : 'materialized';
+  return result(status, plan, created, input, findings, remaining);
+}
+
+function result(status, plan, created, input, findings, remaining = plan.unassignedFindings || []) {
+  const baseSession = input.session || input.snapshot || {
+    files: input.files || [],
+    records: input.records || [],
+    assets: input.assets || [],
+    durableFindings: plan.durableFindings,
+    stagedArtifacts: input.stagedArtifacts || []
+  };
+  const existingStaged = baseSession.stagedArtifacts || baseSession.materials?.stagedArtifacts || [];
+  const newStaged = created.map((item) => item.stagedArtifact).filter(Boolean);
+  const session = openPortableSession({
+    ...baseSession,
+    materials: baseSession.materials,
+    durableFindings: remaining,
+    stagedArtifacts: [...existingStaged, ...newStaged]
+  }).snapshot();
+  const findingSummary = summarizePortableFindings(findings);
+  return Object.freeze({
+    schema: PORTABLE_DURABLE_MATERIALIZATION_RESULT_SCHEMA_ID,
+    status,
+    plan,
+    materialized: Object.freeze(created),
+    remainingFindings: Object.freeze(remaining),
+    session,
+    boundary: Object.freeze({ schemaSelectionWasExplicit: true, localDraftsOnly: true, remoteWrite: false, sourceMutation: false }),
+    findings: Object.freeze(findings),
+    findingSummary
+  });
+}
+
+function normalizeFindings(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return list.map((finding, index) => Object.freeze({ ...finding, id: findingId(finding, index) }));
+}
+
+function normalizeSpecs(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return list.map((spec, index) => Object.freeze({
+    ...spec,
+    id: String(spec?.id || `materialization-${index + 1}`),
+    schemaId: String(spec?.schemaId || ''),
+    findingIds: Object.freeze((Array.isArray(spec?.findingIds) ? spec.findingIds : spec?.findingId ? [spec.findingId] : []).map(String)),
+    values: Object.freeze({ ...(spec?.values || {}) }),
+    sections: Object.freeze({ ...(spec?.sections || {}) })
+  }));
+}
+
+function findingId(finding = {}, index = 0) {
+  return String(finding.id || finding.code || `finding-${index + 1}`);
+}
+
+function mergeFiles(left, right) {
+  const map = new Map();
+  for (const file of [...left, ...right]) map.set(`${file.path}:${String(file.content || '').length}`, file);
+  return [...map.values()];
+}
+
+function dedupeNewFindings(existing, next) {
+  return next.filter((finding) => !existing.some((item) => item.code === finding.code && item.message === finding.message && item.ref === finding.ref));
+}

package/src/tooling/portable/materialization/epistemic.plan.js

@@ -0,0 +1,239 @@
+import { listCreatableArtifactSchemas, buildArtifactCreationContract } from '../../../schemas/creation.contracts.js';
+import { resolveLineage } from '../../../lineage/lineage.resolve.js';
+import { normalizePortableInput } from '../input/portable.input.js';
+import { portableFinding, summarizePortableFindings } from '../findings.js';
+import { planPortableArtifact } from '../schema/schema.guide.js';
+import { indexPortableLoadedParentRecords, projectPortableLoadedParentRecord, resolvePortableLoadedParentReference } from './loaded.parent.js';
+import { allocateContinuationPath, allocateRootArtifactPath } from '../../../transitions/record.transitions.js';
+
+export const PORTABLE_EPISTEMIC_PLAN_SCHEMA_ID = 'tiinex.portable.epistemic-materialization-plan.v1';
+
+export function prepareEpistemicMaterialization(input = {}, options = {}) {
+  const material = normalizePortableInput(input.materials || input);
+  const proposals = normalizeProposals(input.proposals || input.proposal || []);
+  const artifactRecords = material.records.filter(isArtifactRecord);
+  const lineage = resolveLineage(artifactRecords, { depth: 'portable-epistemic-plan' });
+  const loadedIndex = indexPortableLoadedParentRecords(artifactRecords);
+  const proposalIds = new Set(proposals.map((proposal) => proposal.id));
+  const candidateSchemas = listCreatableArtifactSchemas().map((contract) => Object.freeze({
+    schemaId: contract.target.schemaId,
+    label: contract.target.label,
+    role: contract.target.role,
+    transitionType: contract.transitionType,
+    status: contract.status,
+    binding: contract.target.binding
+  }));
+  const parentCandidates = lineageParentCandidates(lineage);
+  const findings = [...(material.findings || []), ...(lineage.findings || []).map((finding) => portableFinding(finding.severity, finding.code, finding.message, finding))];
+
+  if (!proposals.length) {
+    findings.push(portableFinding('info', 'portable.materialization.proposal.required', 'No artifact proposal was supplied. The LLM should form a bounded proposal from the dialogue before materialization.', { qualification: 'epistemic-planning' }));
+    return finalize({
+      status: 'needs-proposal',
+      material: { ...material, records: artifactRecords },
+      proposals: [],
+      candidateSchemas,
+      parentCandidates,
+      lineage,
+      findings,
+      clarificationNeeds: [{ code: 'proposal', statement: 'Declare what knowledge should be preserved, in which implemented schema, and whether it is a new root or continues an explicit loaded/proposed Parent.' }]
+    });
+  }
+
+  const planned = [];
+  const plannedById = new Map();
+  const occupiedPaths = new Set([
+    ...(material.records || []).map((record) => clean(record?.path || '')),
+    ...(material.files || []).map((file) => clean(file?.path || ''))
+  ].filter(Boolean));
+  for (let index = 0; index < proposals.length; index += 1) {
+    const proposal = proposals[index];
+    const entry = planProposal({ proposal, index, proposals, proposalIds, loadedIndex, material, options, plannedById, occupiedPaths });
+    planned.push(entry);
+    plannedById.set(entry.id, entry);
+    if (entry.path) occupiedPaths.add(entry.path);
+  }
+  findings.push(...planned.flatMap((entry) => entry.findings));
+  const clarificationNeeds = planned.flatMap((entry) => entry.clarificationNeeds.map((need) => ({ proposalId: entry.id, ...need })));
+  const status = planned.some((entry) => entry.status === 'blocked')
+    ? 'blocked'
+    : clarificationNeeds.length
+      ? 'needs-clarification'
+      : 'ready';
+
+  return finalize({ status, material: { ...material, records: artifactRecords }, proposals: planned, candidateSchemas, parentCandidates, lineage, findings, clarificationNeeds });
+}
+
+function planProposal({ proposal, index, proposals, proposalIds, loadedIndex, material, options, plannedById, occupiedPaths }) {
+  const findings = [];
+  const clarificationNeeds = [];
+  const contract = buildArtifactCreationContract({ schemaId: proposal.schemaId, transitionType: proposal.parentRef ? 'continue-from-record' : 'create-artifact' });
+  const artifactPlan = planPortableArtifact({ ...material, schemaId: proposal.schemaId, task: proposal.parentRef ? 'continue' : 'create', values: proposal.values || {}, inputs: proposal.values || {} }, options);
+  const parent = resolveParentReference(proposal.parentRef, { loadedIndex, proposalIds, proposalIndex: index, proposals });
+  const parentForAllocation = parent.status === 'resolved'
+    ? parent.kind === 'proposal'
+      ? plannedParentRecord(plannedById.get(parent.parent?.proposalId || ''))
+      : parent.parent
+    : null;
+  const allocationOptions = Object.freeze({ existingPaths: Object.freeze([...occupiedPaths]), path: proposal.path || '' });
+  const allocated = proposal.parentRef && parentForAllocation
+    ? allocateContinuationPath({ parentRecord: parentForAllocation, targetId: proposal.schemaId, targetLabel: proposal.schemaId, title: proposal.title || proposal.summary || proposal.id }, allocationOptions)
+    : !proposal.parentRef
+      ? allocateRootArtifactPath({ targetId: proposal.schemaId, targetLabel: proposal.schemaId, title: proposal.title || proposal.summary || proposal.id }, allocationOptions)
+      : Object.freeze({ path: proposal.path || '', policy: Object.freeze({}) });
+
+  if (!proposal.schemaId) {
+    findings.push(portableFinding('error', 'portable.materialization.schema.required', 'Each proposal must declare an implemented schema id; schema meaning is never inferred by the writer.', { proposalId: proposal.id }));
+    clarificationNeeds.push({ code: 'schema', statement: 'Choose one implemented schema using the dialogue purpose and schema companion guidance.' });
+  } else if (contract.status !== 'ready') {
+    findings.push(...(contract.findings || []).map((finding) => portableFinding(finding.severity, finding.code, finding.message, { ...finding, proposalId: proposal.id })));
+  }
+
+  if (proposal.parentRef && parent.status !== 'resolved') {
+    findings.push(portableFinding('error', parent.code, parent.message, { proposalId: proposal.id, parentRef: proposal.parentRef, candidates: parent.candidates || [] }));
+    clarificationNeeds.push({ code: 'parent', statement: 'Select one exact loaded artifact or one earlier proposal as Parent. Do not infer a Parent from title similarity, Origin, or basename.' });
+  }
+  if (!proposal.parentRef && proposal.mode === 'continue') {
+    findings.push(portableFinding('error', 'portable.materialization.parent.required', 'Continuation mode requires an explicit Parent reference.', { proposalId: proposal.id }));
+    clarificationNeeds.push({ code: 'parent', statement: 'Declare the exact Parent or change the proposal to a new lineage root.' });
+  }
+  if (proposal.mode === 'root' && proposal.parentRef) findings.push(portableFinding('error', 'portable.materialization.root.parent-conflict', 'A root proposal must not declare a Parent.', { proposalId: proposal.id }));
+  if (!proposal.rationale) {
+    findings.push(portableFinding('warning', 'portable.materialization.rationale.missing', 'The proposal should state why this artifact is warranted by the dialogue or loaded material.', { proposalId: proposal.id, fixability: 'manual' }));
+    clarificationNeeds.push({ code: 'rationale', statement: 'State the smallest evidence-grounded reason this artifact should exist.' });
+  }
+  if (!proposal.evidenceRefs.length) {
+    findings.push(portableFinding('warning', 'portable.materialization.evidence-refs.missing', 'The proposal should bind its rationale to dialogue turns or loaded artifact paths.', { proposalId: proposal.id, fixability: 'manual' }));
+    clarificationNeeds.push({ code: 'evidence', statement: 'Reference the dialogue turn(s) or loaded artifact path(s) that support the proposal.' });
+  }
+  if (artifactPlan.plan.missingInputs.length) {
+    findings.push(portableFinding('warning', 'portable.materialization.inputs.missing', 'The proposed artifact is missing schema-required authoring inputs.', { proposalId: proposal.id, schemaId: proposal.schemaId, missingInputs: artifactPlan.plan.missingInputs }));
+    clarificationNeeds.push({ code: 'inputs', statement: `Obtain only the missing schema inputs: ${artifactPlan.plan.missingInputs.join(', ')}.` });
+  }
+
+  const blocking = findings.some((finding) => finding.severity === 'error');
+  return Object.freeze({
+    id: proposal.id,
+    order: index + 1,
+    status: blocking ? 'blocked' : clarificationNeeds.length ? 'needs-clarification' : 'ready',
+    mode: proposal.parentRef ? 'continue-lineage' : 'new-lineage-root',
+    schemaId: proposal.schemaId,
+    path: allocated.path || proposal.path,
+    title: proposal.title,
+    summary: proposal.summary,
+    why: proposal.why,
+    values: proposal.values,
+    sections: proposal.sections,
+    bodyMarkdown: proposal.bodyMarkdown,
+    schemaReferences: proposal.schemaReferences,
+    createdAt: proposal.createdAt,
+    rationale: proposal.rationale,
+    evidenceRefs: proposal.evidenceRefs,
+    parentRef: proposal.parentRef,
+    parent: parent.status === 'resolved' ? parent.parent : null,
+    parentKind: parent.status === 'resolved' ? parent.kind : '',
+    creationContract: contract,
+    artifactPlan: artifactPlan.plan,
+    clarificationNeeds: Object.freeze(clarificationNeeds),
+    findings: Object.freeze(findings)
+  });
+}
+
+function normalizeProposals(value) {
+  const list = Array.isArray(value) ? value : value && typeof value === 'object' ? [value] : [];
+  return Object.freeze(list.map((raw, index) => {
+    const id = clean(raw.id || `artifact-${index + 1}`);
+    return Object.freeze({
+      id,
+      mode: clean(raw.mode || ''),
+      schemaId: clean(raw.schemaId || raw.schema || ''),
+      parentRef: exact(raw.parentRef ?? raw.parent ?? ''),
+      path: clean(raw.path || ''),
+      title: clean(raw.title || ''),
+      summary: clean(raw.summary || ''),
+      why: clean(raw.why || raw.rationale || ''),
+      values: clone(raw.values || {}),
+      sections: clone(raw.sections || {}),
+      bodyMarkdown: String(raw.bodyMarkdown || ''),
+      schemaReferences: raw.schemaReferences && typeof raw.schemaReferences === 'object' ? Object.freeze(clone(raw.schemaReferences)) : null,
+      createdAt: clean(raw.createdAt || ''),
+      rationale: clean(raw.rationale || ''),
+      evidenceRefs: Object.freeze(normalizeStrings(raw.evidenceRefs || raw.evidence || []))
+    });
+  }));
+}
+
+function plannedParentRecord(entry = null) {
+  if (!entry?.path) return null;
+  return Object.freeze({ id: entry.id || '', path: entry.path, schemaId: entry.schemaId || '', title: entry.title || entry.summary || entry.id || '' });
+}
+
+function resolveParentReference(ref, { loadedIndex, proposalIds, proposalIndex, proposals }) {
+  if (!ref) return { status: 'none', kind: 'none', parent: null };
+  const reference = exact(ref);
+  const proposalRef = reference.startsWith('proposal:') ? reference.slice('proposal:'.length) : proposalIds.has(reference) ? reference : '';
+  if (proposalRef) {
+    const targetIndex = proposals.findIndex((proposal) => proposal.id === proposalRef);
+    if (targetIndex < 0) return { status: 'missing', code: 'portable.materialization.parent.proposal-missing', message: 'The Parent proposal does not exist.', candidates: [] };
+    if (targetIndex >= proposalIndex) return { status: 'invalid-order', code: 'portable.materialization.parent.proposal-order', message: 'A proposal may only continue an earlier proposal in the same artifact set.', candidates: [proposalRef] };
+    return { status: 'resolved', kind: 'proposal', parent: Object.freeze({ proposalId: proposalRef }) };
+  }
+  const resolved = resolvePortableLoadedParentReference(reference, loadedIndex);
+  if (resolved.status === 'missing') return { status: 'missing', code: 'portable.materialization.parent.missing', message: 'The declared Parent reference is not present in loaded material.', candidates: [] };
+  if (resolved.status === 'ambiguous') return { status: 'ambiguous', code: 'portable.materialization.parent.ambiguous', message: 'The declared Parent reference matches multiple loaded records.', candidates: resolved.candidates.map((record) => record.id || record.path) };
+  return { status: 'resolved', kind: 'loaded-record', parent: projectPortableLoadedParentRecord(resolved.record) };
+}
+
+function lineageParentCandidates(lineage = {}) {
+  const childIds = new Set((lineage.edges || []).filter((edge) => edge.kind === 'parent' && edge.from).map((edge) => edge.from));
+  return Object.freeze((lineage.nodes || []).map((node) => Object.freeze({
+    id: node.id,
+    path: node.path,
+    title: node.title,
+    schemaId: node.schemaId,
+    sourceMode: node.sourceMode,
+    boundary: node.boundary,
+    role: childIds.has(node.id) ? 'ancestor-or-branch' : 'loaded-leaf-candidate',
+    explicitOnly: true
+  })));
+}
+
+function finalize({ status, material, proposals, candidateSchemas, parentCandidates, lineage, findings, clarificationNeeds }) {
+  const summary = summarizePortableFindings(findings);
+  return Object.freeze({
+    schema: PORTABLE_EPISTEMIC_PLAN_SCHEMA_ID,
+    status,
+    material: Object.freeze({ records: material.records.length, files: material.files.length, sourceMode: material.sourceMode || '', boundary: material.boundary || null }),
+    candidateSchemas: Object.freeze(candidateSchemas),
+    parentCandidates: Object.freeze(parentCandidates),
+    proposals: Object.freeze(proposals),
+    clarificationNeeds: Object.freeze(clarificationNeeds),
+    lineage: Object.freeze({ stats: lineage.stats, findings: Object.freeze(lineage.findings || []) }),
+    epistemicBoundary: Object.freeze({
+      fixedQuestionnaire: false,
+      oneQuestionAtATimeWhenBlocked: true,
+      materializationMustBeEvidenceGrounded: true,
+      schemaSelectionMustUseSharedCompanion: true,
+      parentMustBeExplicitLoadedOrEarlierProposal: true,
+      originIsNotParent: true,
+      sourceProvenanceIsNeverGuessed: true,
+      noArtifactIsAlsoAValidOutcome: true
+    }),
+    findings: Object.freeze(findings),
+    findingSummary: summary
+  });
+}
+
+function isArtifactRecord(record = {}) {
+  const path = String(record.path || '').toLowerCase();
+  const role = String(record.materialRole || '').toLowerCase();
+  if (path.endsWith('.schema.md') || path.includes('/canonical/schemas/')) return false;
+  if (role.includes('schema') || role.includes('supporting')) return false;
+  return Boolean(record.hasContinuityContext || record.schemaId || record.kind?.startsWith?.('tiinex.'));
+}
+
+function normalizeStrings(value) { return [...new Set((Array.isArray(value) ? value : [value]).map(clean).filter(Boolean))]; }
+function clean(value) { return String(value || '').replace(/\s+/g, ' ').trim(); }
+function exact(value) { return String(value ?? ''); }
+function slug(value) { return clean(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'artifact'; }
+function clone(value) { return value == null ? {} : JSON.parse(JSON.stringify(value)); }

package/src/tooling/portable/materialization/loaded.parent.js

@@ -0,0 +1,54 @@
+export function indexPortableLoadedParentRecords(records = []) {
+  const index = new Map();
+  for (const record of records) {
+    for (const key of exactLoadedIdentityKeys(record)) {
+      const list = index.get(key) || [];
+      if (!list.includes(record)) list.push(record);
+      index.set(key, list);
+    }
+  }
+  return index;
+}
+
+export function resolvePortableLoadedParentReference(ref = '', indexOrRecords = []) {
+  const reference = exact(ref);
+  if (!reference) return Object.freeze({ status: 'missing', candidates: Object.freeze([]), record: null });
+  const index = indexOrRecords instanceof Map ? indexOrRecords : indexPortableLoadedParentRecords(indexOrRecords);
+  const candidates = index.get(reference) || [];
+  if (candidates.length !== 1) return Object.freeze({
+    status: candidates.length ? 'ambiguous' : 'missing',
+    candidates: Object.freeze(candidates.slice()),
+    record: null
+  });
+  return Object.freeze({ status: 'resolved', candidates: Object.freeze(candidates.slice()), record: candidates[0] });
+}
+
+export function projectPortableLoadedParentRecord(record = {}) {
+  const id = exact(record.id || record.path || '');
+  return Object.freeze({
+    id,
+    path: exact(record.path || ''),
+    kind: exact(record.kind || ''),
+    schemaId: exact(record.schemaId || ''),
+    currentSchemaId: exact(record.currentSchemaId || ''),
+    currentCreatedAt: exact(record.currentCreatedAt || ''),
+    createdAt: exact(record.createdAt || ''),
+    continuationTrace: '',
+    boundary: exact(record.boundary || record.source?.boundary || 'loaded material boundary'),
+    sourceMode: exact(record.sourceMode || ''),
+    source: record.source || null,
+    markdown: exact(record.markdown || ''),
+    integrity: record.integrity || null,
+    publishedReference: record.publishedReference || null,
+    schemaReferenceAuthority: record.schemaReferenceAuthority || null,
+    title: exact(record.title || ''),
+    summary: exact(record.summary || '')
+  });
+}
+
+function exactLoadedIdentityKeys(record = {}) {
+  const keys = [exact(record.id || ''), exact(record.path || '')].filter((value) => value !== '');
+  return [...new Set(keys)];
+}
+
+function exact(value) { return String(value ?? ''); }

package/src/tooling/portable/materialization/materialization.facade.js

@@ -0,0 +1,30 @@
+import { portableOperationResult as operationResult } from '../operation.result.js';
+import { createPortableLocalArtifactSet } from '../draft/draft.set.js';
+import { prepareEpistemicMaterialization } from './epistemic.plan.js';
+
+export function preparePortableMaterialization(input = {}, options = {}) {
+  const result = prepareEpistemicMaterialization(input, options);
+  return operationResult('prepare-materialization', {
+    status: result.status,
+    material: result.material,
+    candidateSchemas: result.candidateSchemas,
+    parentCandidates: result.parentCandidates,
+    proposals: result.proposals,
+    clarificationNeeds: result.clarificationNeeds,
+    lineage: result.lineage,
+    epistemicBoundary: result.epistemicBoundary,
+    findings: result.findings
+  });
+}
+
+export function createPortableArtifactSet(input = {}, options = {}) {
+  const result = createPortableLocalArtifactSet(input, options);
+  return operationResult('create-local-artifact-set', {
+    status: result.status,
+    plan: result.plan,
+    artifacts: result.artifacts,
+    lineageClosure: result.lineageClosure,
+    boundary: result.boundary,
+    findings: result.findings
+  });
+}