@tiinex/core 0.1.1

package/src/tooling/portable/live/live.artifact.js

@@ -0,0 +1,192 @@
+import { buildArtifactCreationContract } from '../../../schemas/creation.contracts.js';
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+import { createPortableLocalDraft } from '../draft/draft.create.js';
+import { portableFinding } from '../findings.js';
+import { projectPortableLoadedParentRecord, resolvePortableLoadedParentReference } from '../materialization/loaded.parent.js';
+import { allocateContinuationPath, allocateRootArtifactPath } from '../../../transitions/record.transitions.js';
+
+export function materializeLiveArtifact({ current, change, material, artifacts, findings, input, options }) {
+  if (Object.prototype.hasOwnProperty.call(change, 'bodyMarkdown') && String(change.bodyMarkdown || '').trim()) {
+    findings.push(portableFinding('error', 'live-lineage.body-markdown.blocked', 'Use schema-owned values and sections; raw Markdown replacement is blocked.', { artifactId: change.id }));
+    return null;
+  }
+  const schemaId = clean(change.schemaId || current?.schemaId || '');
+  const transitionType = change.parentRef || current?.parentRef ? 'continue-from-record' : 'create-artifact';
+  const contract = buildArtifactCreationContract({ schemaId, transitionType });
+  if (contract.status !== 'ready') {
+    findings.push(...(contract.findings || []).map((finding) => portableFinding(finding.severity, finding.code, finding.message, { ...finding, artifactId: change.id })));
+    return null;
+  }
+  if (current && schemaId !== current.schemaId) {
+    findings.push(portableFinding('error', 'live-lineage.schema-change.blocked', 'Create a new artifact to change schema.', { artifactId: change.id, before: current.schemaId, after: schemaId }));
+    return null;
+  }
+
+  const parentRef = exact(change.parentRef !== undefined ? change.parentRef : current?.parentRef || '');
+  if (current && parentRef !== current.parentRef) {
+    findings.push(portableFinding('error', 'live-lineage.parent-change.blocked', 'Parent cannot change; create a child or repair continuity.', { artifactId: change.id, before: current.parentRef, after: parentRef }));
+    return null;
+  }
+  const parentRecord = resolveParentRecord(parentRef, material, artifacts, findings);
+  if (parentRef && !parentRecord) return null;
+
+  const explicitOrCurrentPath = change.path || current?.path || '';
+  const allocationOptions = Object.freeze({
+    existingPaths: Object.freeze([
+      ...(material.records || []).map((record) => String(record?.path || '')),
+      ...[...artifacts.values()].map((artifact) => String(artifact?.path || ''))
+    ].filter(Boolean))
+  });
+  const allocatedPath = explicitOrCurrentPath || (parentRecord
+    ? allocateContinuationPath({ parentRecord, targetId: schemaId, targetLabel: schemaId, title: change.title || current?.title || change.id }, allocationOptions).path
+    : allocateRootArtifactPath({ targetId: schemaId, targetLabel: schemaId, title: change.title || current?.title || change.id }, allocationOptions).path);
+  const requestedPath = explicitOrCurrentPath || allocatedPath;
+  const pathValue = normalizeArtifactPath(requestedPath);
+  if (!pathValue) {
+    findings.push(portableFinding('error', 'live-lineage.path.reserved-or-invalid', 'Artifact path is invalid or transport-reserved.', { artifactId: change.id, path: String(requestedPath || '') }));
+    return null;
+  }
+  if (current && pathValue !== current.path) {
+    findings.push(portableFinding('error', 'live-lineage.path-change.blocked', 'Path is immutable.', { artifactId: change.id, before: current.path, after: pathValue }));
+    return null;
+  }
+  const evidenceRefs = mergeStrings(current?.evidenceRefs, change.evidenceRefs);
+  const knownEvidence = new Set([
+    ...(input.state?.evidence || []).map((entry) => entry.id),
+    clean(input.turn?.id),
+    ...(material.files || []).map((file) => `loaded:${file.path}`),
+    ...(material.records || []).map((record) => `loaded:${record.path}`)
+  ].filter(Boolean));
+  for (const ref of evidenceRefs) {
+    if (!knownEvidence.has(ref) && !ref.startsWith('loaded:') && !ref.startsWith('dialogue:')) findings.push(portableFinding('error', 'live-lineage.evidence.unresolved', 'Evidence reference is not declared by dialogue or loaded material.', { artifactId: change.id, evidenceRef: ref }));
+  }
+  if (findings.some((finding) => finding.severity === 'error' && finding.artifactId === change.id)) return null;
+
+  const values = mergeObjects(current?.values, change.values || change.valuesPatch);
+  const sections = mergeObjects(current?.sections, change.sections || change.sectionsPatch);
+  const title = clean(change.title || current?.title || change.id);
+  const summary = clean(change.summary || current?.summary || title);
+  const why = clean(change.why || change.rationale || current?.why || 'Maintained as live local Tiinex lineage.');
+  const runtimeObservedAt = timestamp(input.runtimeObservedAt || runtimeTimestamp(options));
+  const createdAt = current?.createdAt || runtimeObservedAt;
+  const result = createPortableLocalDraft({
+    ...material,
+    schemaId,
+    id: change.id,
+    path: pathValue,
+    title,
+    summary,
+    why,
+    values,
+    sections,
+    createdAt,
+    schemaReferences: change.schemaReferences || input.schemaReferences || null,
+    transitionType: contract.transitionType || transitionType,
+    parentRecord: parentRecord || {},
+    allowIncomplete: change.allowIncomplete !== false
+  }, options);
+  const creationErrors = (result.findings || []).filter((finding) => finding.severity === 'error');
+  if (!result.draft) {
+    findings.push(...creationErrors.map((finding) => portableFinding(finding.severity, finding.code, finding.message, { ...finding, artifactId: change.id })));
+    return null;
+  }
+  const retainedLocalContinuity = result.status === 'created-local-continuity' && result.qualification?.localContinuityUsable === true;
+  if (!retainedLocalContinuity) findings.push(...creationErrors.map((finding) => portableFinding(finding.severity, finding.code, finding.message, { ...finding, artifactId: change.id })));
+
+  const revision = current ? current.revision + 1 : 1;
+  const exportReady = result.status === 'created-clean' && result.qualification?.exactRuntimeValidation === true;
+  return freezeArtifact({
+    id: change.id,
+    schemaId,
+    path: pathValue,
+    parentRef,
+    title,
+    summary,
+    why,
+    values,
+    sections,
+    evidenceRefs,
+    rationale: clean(change.rationale || current?.rationale || ''),
+    status: exportReady ? 'live-clean' : 'live-incomplete',
+    exportReady,
+    revision,
+    createdAt,
+    updatedAt: runtimeObservedAt,
+    draft: result.draft,
+    validation: result.validation,
+    qualification: result.qualification,
+    changeRole: current?.changeRole || 'created',
+    baseSha256: current?.baseSha256 || ''
+  });
+}
+
+function resolveParentRecord(parentRef, material, artifacts, findings) {
+  if (!parentRef) return null;
+  if (parentRef.startsWith('live:')) {
+    const id = parentRef.slice(5);
+    const parent = artifacts.get(id);
+    if (!parent || parent.status === 'withdrawn') {
+      findings.push(portableFinding('error', 'live-lineage.parent.live-missing', 'Declared live Parent does not exist.', { parentRef }));
+      return null;
+    }
+    const parsed = safeParse(parent.draft?.markdown || '');
+    const currentSchema = parsed?.envelope?.current?.schema || {};
+    return Object.freeze({
+      id: parent.id,
+      path: parent.path,
+      schemaId: parent.schemaId,
+      createdAt: parent.draft?.createdAt || parent.createdAt,
+      continuationTrace: '',
+      schemaReferenceAuthority: currentSchema.target ? Object.freeze({
+        schemaId: currentSchema.id || parent.schemaId,
+        preferredTarget: currentSchema.target,
+        exactTargets: Object.freeze([currentSchema.target]),
+        resolutionState: 'qualified',
+        evidence: Object.freeze({ source: 'live-parent-rendered-current-schema-reference' })
+      }) : null,
+      boundary: 'portable local artifact; no remote provenance',
+      sourceMode: 'local-portable-live',
+      source: null,
+      markdown: String(parent.draft?.markdown || ''),
+      integrity: parsed?.integrity || null
+    });
+  }
+  if (parentRef.startsWith('loaded:')) {
+    const wanted = parentRef.slice(7);
+    const resolved = resolvePortableLoadedParentReference(wanted, material.records || []);
+    if (resolved.status !== 'resolved') {
+      findings.push(portableFinding('error', resolved.status === 'ambiguous' ? 'live-lineage.parent.loaded-ambiguous' : 'live-lineage.parent.loaded-missing', resolved.status === 'ambiguous' ? 'Declared loaded Parent is ambiguous.' : 'Loaded Parent is unavailable.', { parentRef, matches: resolved.candidates.length }));
+      return null;
+    }
+    return projectPortableLoadedParentRecord(resolved.record);
+  }
+  findings.push(portableFinding('error', 'live-lineage.parent.ref-invalid', 'Use live:<id> or loaded:<exact-path-or-id> for Parent.', { parentRef }));
+  return null;
+}
+
+function safeParse(markdown = '') {
+  try { return parseArtifactMarkdown(markdown); }
+  catch { return null; }
+}
+
+function freezeArtifact(value = {}) {
+  return Object.freeze({
+    ...value,
+    id: clean(value.id), schemaId: clean(value.schemaId), path: normalizeArtifactPath(value.path || ''), parentRef: exact(value.parentRef), title: clean(value.title), summary: clean(value.summary), why: clean(value.why),
+    values: Object.freeze(clone(value.values || {})), sections: Object.freeze(clone(value.sections || {})), evidenceRefs: Object.freeze(normalizeStrings(value.evidenceRefs)),
+    revision: Math.max(1, Number(value.revision || 1)), status: clean(value.status || 'live-incomplete'), exportReady: value.exportReady === true,
+    draft: value.draft ? Object.freeze({ ...value.draft }) : null, validation: value.validation ? Object.freeze({ ...value.validation }) : null, qualification: value.qualification ? Object.freeze({ ...value.qualification }) : null
+  });
+}
+function defaultArtifactPath(id, title) { const stem = slug(id || title || 'topic'); return `.topics/${slug(title || id || 'lineage')}/${stem}.trace.md`; }
+function normalizeArtifactPath(value) { const cleanPath = String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').replace(/\.\.(?:\/|$)/g, '').trim(); if (!cleanPath) return ''; const withSuffix = cleanPath.toLowerCase().endsWith('.trace.md') ? cleanPath : cleanPath.replace(/\.md$/i, '') + '.trace.md'; return withSuffix.startsWith('.bootstrap/') || withSuffix === '.bootstrap' ? '' : withSuffix; }
+function mergeObjects(before, patch) { return { ...clone(before || {}), ...clone(patch || {}) }; }
+function mergeStrings(...values) { return normalizeStrings(values.flatMap((value) => normalizeArray(value))); }
+function normalizeStrings(value) { return [...new Set(normalizeArray(value).map(clean).filter(Boolean))].sort(); }
+function normalizeArray(value) { return Array.isArray(value) ? value : value == null ? [] : [value]; }
+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, '').slice(0, 80) || 'artifact'; }
+function timestamp(value) { const text = String(value || '').trim(); return text || new Date().toISOString(); }
+function runtimeTimestamp(options = {}) { const value = typeof options.clock === 'function' ? options.clock() : new Date().toISOString(); const date = value instanceof Date ? value : new Date(value); return Number.isNaN(date.getTime()) ? new Date().toISOString() : date.toISOString(); }
+function clone(value) { return value == null ? {} : JSON.parse(JSON.stringify(value)); }

package/src/tooling/portable/live/live.export.js

@@ -0,0 +1,107 @@
+import { validatePortableDraft } from '../draft/draft.operations.js';
+import { normalizePortableInput } from '../input/portable.input.js';
+import { portableFinding, summarizePortableFindings } from '../findings.js';
+import { buildPortableLiveLineageClosure } from './live.lineage.closure.js';
+import { normalizePortableLiveLineageState } from './live.lineage.js';
+import { appendLiveOperationReceipt, summarizeLiveOperationChain } from './live.protocol.js';
+
+export const PORTABLE_LIVE_LINEAGE_EXPORT_SCHEMA_ID = 'tiinex.portable.live-lineage.export.v1';
+
+export function exportPortableLiveLineage(input = {}, options = {}) {
+  const findings = [];
+  const state = normalizePortableLiveLineageState(input.state || input.liveLineage || {}, findings);
+  const material = normalizePortableInput(input.materials || input);
+  const selectedIds = new Set(normalizeStrings(input.artifactIds));
+  const selected = state.artifacts.filter((entry) => entry.status !== 'withdrawn' && (!selectedIds.size || selectedIds.has(entry.id)));
+  const updateReceipts = state.receipts.filter((entry) => entry.operation === 'update-live-lineage');
+  const prepareReceipts = state.receipts.filter((entry) => entry.operation === 'prepare-live-response');
+  const dialogueMode = classifyDialogueMode(updateReceipts, prepareReceipts);
+
+  if (!selected.length) findings.push(portableFinding('error', 'live-lineage.export.empty', 'No active live artifacts are available for export.'));
+  if (state.protocol.latestTurnSequence > state.protocol.preparedTurnSequence) findings.push(portableFinding('error', 'live-lineage.export.response-preflight-pending', 'Export is blocked because the latest dialogue turn was not processed into bounded response context.', { latestTurnSequence: state.protocol.latestTurnSequence, preparedTurnSequence: state.protocol.preparedTurnSequence }));
+  if (!updateReceipts.length) findings.push(portableFinding('error', 'live-lineage.export.turn-receipt-missing', 'Export requires at least one recorded dialogue-turn transaction.'));
+  if (prepareReceipts.length !== updateReceipts.length) findings.push(portableFinding('error', 'live-lineage.export.turn-pair-incomplete', 'Every recorded dialogue turn must have one response-preflight receipt before export.', { turnReceipts: updateReceipts.length, responseReceipts: prepareReceipts.length }));
+  if (!updateReceipts.some((entry) => entry.decision === 'artifact-change')) findings.push(portableFinding('error', 'live-lineage.export.artifact-change-receipt-missing', 'Export requires an artifact change recorded during a dialogue-turn transaction.'));
+  if (input.requireInterleaved === true && dialogueMode !== 'live-interleaved') findings.push(portableFinding('error', 'live-lineage.export.interleaved-required', 'This acceptance profile requires at least two processed dialogue turns before export.', { dialogueMode, turns: updateReceipts.length }));
+
+  const artifacts = [];
+  for (const entry of selected) {
+    const validation = validatePortableDraft({ ...material, ...entry.draft, schemaId: entry.schemaId }, options);
+    findings.push(...(validation.findings || []).filter((finding) => finding.severity === 'error').map((finding) => portableFinding(finding.severity, finding.code, finding.message, { ...finding, artifactId: entry.id })));
+    if (validation.status !== 'clean') findings.push(portableFinding('error', 'live-lineage.export.validation-blocked', 'Live artifact is not clean under the shared validator and cannot be exported.', { artifactId: entry.id, validationStatus: validation.status }));
+    artifacts.push(Object.freeze({
+      proposalId: entry.id,
+      parentProposalId: entry.parentRef.startsWith('live:') ? entry.parentRef.slice(5) : '',
+      parentLoadedRef: entry.parentRef.startsWith('loaded:') ? entry.parentRef.slice(7) : '',
+      draft: Object.freeze({ ...entry.draft, changeRole: entry.changeRole || 'created', baseSha256: entry.baseSha256 || '' }),
+      validation
+    }));
+  }
+
+  const lineageClosure = buildPortableLiveLineageClosure(material, selected);
+  const hasErrors = findings.some((finding) => finding.severity === 'error');
+  let operationReceipt = summarizeLiveOperationChain({ protocol: state.protocol, receipts: state.receipts });
+  if (!hasErrors) {
+    const appended = appendLiveOperationReceipt({
+      protocol: state.protocol,
+      receipts: state.receipts,
+      operation: 'export-live-lineage',
+      eventSequence: state.protocol.latestEventSequence,
+      coversThroughEventSequence: state.protocol.preparedEventSequence,
+      turnSequence: state.protocol.latestTurnSequence,
+      coversThroughTurnSequence: state.protocol.preparedTurnSequence,
+      latestEventSequence: state.protocol.latestEventSequence,
+      preparedEventSequence: state.protocol.preparedEventSequence,
+      latestTurnSequence: state.protocol.latestTurnSequence,
+      preparedTurnSequence: state.protocol.preparedTurnSequence,
+      exportCount: state.protocol.exportCount + 1,
+      artifactIds: selected.map((entry) => entry.id),
+      clock: options.clock,
+      decision: dialogueMode,
+      details: { artifactCount: selected.length, genericFileFallback: false, dialogueMode, processedTurns: updateReceipts.length }
+    });
+    operationReceipt = summarizeLiveOperationChain({ protocol: appended.protocol, receipts: appended.receipts });
+  }
+  return Object.freeze({
+    schema: PORTABLE_LIVE_LINEAGE_EXPORT_SCHEMA_ID,
+    status: hasErrors ? 'blocked' : 'created-clean',
+    dialogueMode,
+    artifacts: Object.freeze(artifacts),
+    lineageClosure,
+    assets: Object.freeze(normalizeAssets(input.assets)),
+    state: Object.freeze({ schema: state.schema, version: state.version, focusArtifactId: state.focusArtifactId, artifactIds: Object.freeze(selected.map((entry) => entry.id)), protocol: state.protocol }),
+    operationReceipt,
+    boundary: Object.freeze({
+      dialogueMode,
+      processedDialogueTurns: updateReceipts.length,
+      artifactsChangedBeforeExport: updateReceipts.some((entry) => entry.decision === 'artifact-change'),
+      retrospectiveArtifactSynthesis: dialogueMode === 'export-time-synthesis',
+      everyRecordedTurnPrepared: prepareReceipts.length === updateReceipts.length,
+      provesEveryProviderTurnObserved: false,
+      portableOperationReceiptsRecorded: !hasErrors,
+      genericFileFallback: false,
+      sourceMutation: false,
+      remoteWrite: false,
+      bootstrapIncluded: false
+    }),
+    findings: Object.freeze(findings),
+    findingSummary: summarizePortableFindings(findings)
+  });
+}
+
+function classifyDialogueMode(updateReceipts, prepareReceipts) {
+  if (!updateReceipts.length) return 'export-time-synthesis';
+  if (prepareReceipts.length !== updateReceipts.length) return 'unverified';
+  if (updateReceipts.length === 1) return 'single-turn';
+  return 'live-interleaved';
+}
+function normalizeAssets(value) {
+  return normalizeArray(value).filter((entry) => entry && typeof entry === 'object' && (
+    String(entry.path || '').trim()
+    || String(entry.content ?? entry.data ?? '').length
+    || Number(entry.bytes || 0) > 0
+  ));
+}
+function normalizeStrings(value) { return [...new Set(normalizeArray(value).map(clean).filter(Boolean))].sort(); }
+function normalizeArray(value) { return Array.isArray(value) ? value : value == null ? [] : [value]; }
+function clean(value) { return String(value || '').replace(/\s+/g, ' ').trim(); }

package/src/tooling/portable/live/live.lineage.closure.js

@@ -0,0 +1,71 @@
+import { resolveLineage } from '../../../lineage/lineage.resolve.js';
+
+export function buildPortableLiveLineageClosure(material = {}, selected = []) {
+  const records = (material.records || []).filter((record) => record.path && record.markdown && (record.hasContinuityContext || record.schemaId || String(record.kind || '').startsWith('tiinex.')));
+  const lineage = resolveLineage(records, { depth: 'portable-live-lineage-export' });
+  const nodeById = new Map((lineage.nodes || []).map((node) => [node.id, node]));
+  const nodeByPath = new Map((lineage.nodes || []).map((node) => [String(node.path || ''), node]));
+  const selectedLoaded = collectLoadedParents(selected, lineage, nodeById, nodeByPath);
+  const context = [...selectedLoaded]
+    .map((id) => nodeById.get(id))
+    .filter(Boolean)
+    .map((node) => Object.freeze({
+      id: node.id,
+      path: node.path,
+      schemaId: node.schemaId,
+      markdown: String(node.record?.markdown || ''),
+      trace: String(node.trace || ''),
+      parentSchemaId: String(node.parentSchemaId || ''),
+      sourceMode: String(node.sourceMode || ''),
+      boundary: String(node.boundary || '')
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  const edges = collectEdges(selected, lineage, selectedLoaded, nodeById, nodeByPath);
+  return Object.freeze({
+    schema: 'tiinex.portable.lineage-closure.v1',
+    context: Object.freeze(context),
+    edges: Object.freeze(uniqueEdges(edges)),
+    boundary: 'Minimum known Parent closure for live artifacts. Exact loaded Parent bytes are preserved as unchanged context.'
+  });
+}
+
+function collectLoadedParents(selected, lineage, nodeById, nodeByPath) {
+  const selectedLoaded = new Set();
+  const queue = selected.filter((entry) => entry.parentRef.startsWith('loaded:')).map((entry) => entry.parentRef.slice(7));
+  while (queue.length) {
+    const ref = queue.shift();
+    const node = nodeByPath.get(ref) || nodeById.get(ref);
+    if (!node || selectedLoaded.has(node.id)) continue;
+    selectedLoaded.add(node.id);
+    for (const edge of lineage.edges || []) if (edge.kind === 'parent' && edge.to === node.id && edge.from) queue.push(edge.from);
+  }
+  return selectedLoaded;
+}
+
+function collectEdges(selected, lineage, selectedLoaded, nodeById, nodeByPath) {
+  const selectedById = new Map(selected.map((entry) => [entry.id, entry]));
+  const edges = [];
+  for (const edge of lineage.edges || []) {
+    if (edge.kind !== 'parent' || !selectedLoaded.has(edge.from) || !selectedLoaded.has(edge.to)) continue;
+    const parent = nodeById.get(edge.from);
+    const child = nodeById.get(edge.to);
+    if (parent?.path && child?.path) edges.push({ childPath: child.path, parentPath: parent.path, parentKind: 'loaded-context' });
+  }
+  for (const entry of selected) {
+    if (entry.parentRef.startsWith('live:')) {
+      const parent = selectedById.get(entry.parentRef.slice(5));
+      if (parent) edges.push({ childPath: entry.path, parentPath: parent.path, parentKind: 'created-live' });
+    } else if (entry.parentRef.startsWith('loaded:')) {
+      const ref = entry.parentRef.slice(7);
+      const parent = nodeByPath.get(ref) || nodeById.get(ref);
+      if (parent?.path) edges.push({ childPath: entry.path, parentPath: parent.path, parentKind: 'loaded-context' });
+    }
+  }
+  return edges;
+}
+
+function uniqueEdges(edges) {
+  const map = new Map();
+  for (const edge of edges) map.set(`${edge.childPath}\0${edge.parentPath}`, Object.freeze(edge));
+  return [...map.values()].sort((a, b) => `${a.childPath}\0${a.parentPath}`.localeCompare(`${b.childPath}\0${b.parentPath}`));
+}