@tiinex/core 0.1.1

package/src/tooling/portable/host/tool.receiptNormalization.js

@@ -0,0 +1,141 @@
+import { portableFinding } from '../findings.js';
+
+export function normalizeRepositoryFiles(normalized, findings, request = {}) {
+  const files = normalizeFiles(normalized);
+  const out = [];
+  for (const file of files) {
+    if (!file.path || typeof file.content !== 'string') {
+      findings.push(portableFinding('error', 'portable.host-receipt.repository-file.invalid', 'Repository read receipts require path and UTF-8 content.', { ref: file.path || '' }));
+      continue;
+    }
+    const source = file.source || normalized.source || {};
+    if (!source.repository) findings.push(portableFinding('error', 'portable.host-receipt.repository-source.missing', 'Repository read receipts require explicit repository identity.', { ref: file.path }));
+    if (!source.commit) findings.push(portableFinding('warning', 'portable.host-receipt.repository-commit.unpinned', 'Repository material was returned without a resolved commit and remains moving-ref qualified.', { ref: file.path, repository: source.repository || '' }));
+    const authority = source.authority === 'canonical-core' && !source.commit ? 'remote-repository-unpinned' : String(source.authority || 'remote-repository-unverified');
+    const normalizedFile = Object.freeze({
+      path: normalizePath(file.path),
+      content: file.content,
+      sourceMode: 'portable-host-repository',
+      source: Object.freeze({
+        repository: String(source.repository || ''),
+        ref: String(source.ref || ''),
+        commit: String(source.commit || ''),
+        path: normalizePath(source.path || file.path),
+        authority,
+        remoteFetch: true,
+        receiptQualification: 'accepted-host-repository-read',
+        provenanceQualification: source.commit ? 'accepted-host-repository-pinned' : 'accepted-host-repository-moving-ref',
+        ...(source.permalink ? { permalink: String(source.permalink) } : {}),
+        ...(source.durableLocator ? { durableLocator: String(source.durableLocator) } : {})
+      })
+    });
+    if (repositoryReadIdentityMatches(request, normalizedFile, findings)) out.push(normalizedFile);
+  }
+  return out;
+}
+
+
+function repositoryReadIdentityMatches(request = {}, file = {}, findings = []) {
+  const expectedRepository = concreteIdentity(request.repository);
+  const expectedRef = concreteIdentity(request.ref);
+  const expectedPath = concretePath(request.path);
+  const source = file?.source || {};
+  const actualRepository = concreteIdentity(source.repository);
+  const actualRef = concreteIdentity(source.ref);
+  const actualCommit = concreteIdentity(source.commit);
+  const actualFilePath = concretePath(file?.path);
+  const actualSourcePath = concretePath(source.path || file?.path);
+  let matches = true;
+  if (expectedRepository && expectedRepository.toLowerCase() !== actualRepository.toLowerCase()) {
+    matches = false;
+    findings.push(portableFinding('error', 'portable.host-receipt.repository-identity.mismatch', 'Repository read receipt does not match the exact requested repository identity.', { expected: expectedRepository, actual: actualRepository, ref: actualFilePath }));
+  }
+  if (expectedPath && (expectedPath !== actualFilePath || expectedPath !== actualSourcePath)) {
+    matches = false;
+    findings.push(portableFinding('error', 'portable.host-receipt.repository-path.mismatch', 'Repository read receipt does not match the exact requested repository path.', { expected: expectedPath, actual: actualSourcePath || actualFilePath, ref: actualFilePath }));
+  }
+  if (expectedRef) {
+    const pinned = /^[0-9a-f]{40}$/i.test(expectedRef);
+    const refMatches = pinned ? actualCommit.toLowerCase() === expectedRef.toLowerCase() : actualRef === expectedRef || actualCommit === expectedRef;
+    if (!refMatches) {
+      matches = false;
+      findings.push(portableFinding('error', 'portable.host-receipt.repository-ref.mismatch', 'Repository read receipt does not match the exact requested repository ref/commit identity.', { expected: expectedRef, actualRef, actualCommit, ref: actualFilePath }));
+    }
+  }
+  return matches;
+}
+
+function concreteIdentity(value = '') {
+  const text = String(value || '').trim();
+  return !text || /^<.*>$/.test(text) ? '' : text;
+}
+
+function concretePath(value = '') {
+  const text = concreteIdentity(value);
+  return text ? normalizePath(text) : '';
+}
+
+export function normalizeLocalFiles(normalized, findings, capabilityName) {
+  const files = normalizeFiles(normalized);
+  return files.flatMap((file) => {
+    if (!file.path || (typeof file.content !== 'string' && !file.locator)) {
+      findings.push(portableFinding('error', 'portable.host-receipt.local-file.invalid', 'Local/archive read receipts require a path plus content or an explicit locator.', { ref: file.path || '' }));
+      return [];
+    }
+    if (file.source?.repository || normalized.source?.repository) findings.push(portableFinding('warning', 'portable.host-receipt.local-source.stripped', 'Repository source metadata was ignored for a local/archive read receipt.', { ref: file.path }));
+    return [Object.freeze({
+      path: normalizePath(file.path),
+      ...(typeof file.content === 'string' ? { content: file.content } : {}),
+      ...(file.locator ? { locator: sanitizeLocator(file.locator) } : {}),
+      sourceMode: capabilityName === 'archiveRead' ? 'portable-host-archive' : 'portable-host-local',
+      source: null
+    })];
+  });
+}
+
+export function normalizeInterpretations(normalized, findings, capabilityName) {
+  if (!normalized.assetPath || !normalized.description) {
+    findings.push(portableFinding('error', 'portable.host-receipt.interpretation.invalid', 'Multimodal receipts require assetPath and a generated description.'));
+    return [];
+  }
+  return [Object.freeze({
+    schema: 'tiinex.portable.asset-analysis-response.v1',
+    assetPath: normalizePath(normalized.assetPath),
+    description: String(normalized.description),
+    observations: Object.freeze(normalizeList(normalized.observations)),
+    qualification: Object.freeze({
+      mode: normalized.qualification?.mode || (capabilityName === 'images' ? 'host-multimodal-image' : 'host-multimodal-pdf'),
+      generatedInterpretation: true,
+      sourceAssetPreserved: true,
+      analysisIsNotSourceMaterial: true
+    })
+  })];
+}
+
+function normalizeFiles(value = {}) {
+  if (Array.isArray(value.files)) return value.files;
+  if (value.file && typeof value.file === 'object') return [value.file];
+  if (value.path || value.content) return [value];
+  return [];
+}
+
+export function normalizeList(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return [...new Set(list.map((item) => String(item || '').trim()).filter(Boolean))];
+}
+
+function sanitizeLocator(locator = {}) {
+  return Object.freeze({
+    kind: String(locator.kind || ''),
+    archivePath: String(locator.archivePath || ''),
+    entryPath: normalizePath(locator.entryPath || ''),
+    localPath: String(locator.localPath || '')
+  });
+}
+
+export function serializableSchema(value) {
+  if (!value || typeof value !== 'object') return value || null;
+  try { return JSON.parse(JSON.stringify(value)); } catch { return null; }
+}
+
+function normalizePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+/g, '/'); }

package/src/tooling/portable/index.js

@@ -0,0 +1,52 @@
+export * from './engine.facade.js';
+export * from './materialization/materialization.facade.js';
+export * from './findings.js';
+export * from './qualification.js';
+export * from './operation.catalog.js';
+export * from './input/portable.input.js';
+export * from './session/portable.session.js';
+export * from './adapters/llm/llm.entrypoint.js';
+export * from './schema/schema.contract.js';
+export * from './schema/named.declarations.js';
+export * from './schema/contract.compile.js';
+export * from './schema/contract.validate.js';
+export * from './schema/contract.field-domain.js';
+export * from './schema/contract.machine-shape.js';
+export * from './schema/lexical.shape.v1.js';
+export * from './schema/contract.semantic-resolution.js';
+export * from './schema/contract.project.js';
+export * from './schema/ordinary.fields.js';
+export * from './schema/schema.snapshot.js';
+export * from './schema/schema.guide.js';
+export * from './schema/llm.companion.js';
+export * from './lineage/lineage.search.js';
+export * from './overview/operatingOverview.js';
+export * from './draft/draft.operations.js';
+export * from './host/host.capabilities.js';
+export * from './host/tool.bindings.js';
+export * from './providers/schema.providers.js';
+export * from './draft/draft.create.js';
+export * from './draft/draft.crud.js';
+export * from './draft/draft.set.js';
+export * from './live/live.lineage.js';
+export * from './live/live.export.js';
+export * from './live/live.protocol.js';
+export * from './materialization/epistemic.plan.js';
+export * from './output/node.artifact-set.js';
+export * from './assets/asset.operations.js';
+export * from './orchestration/task.prepare.js';
+export * from './checkpoint/portable.checkpoint.js';
+export * from './materialization/durable.materialize.js';
+export * from './package/runtime.package.js';
+export * from './publication/runtime.publication.js';
+export * from './package/schema.transition.companion.js';
+export * from './package/semantic.package.js';
+export * from './package/generation.binding.js';
+export * from './conformance/checkpoint.qualification.js';
+
+export * from './transfer/transfer.plan.js';
+
+export * from './handoff/manufacture.js';
+export * from './handoff/carrierProfile.js';
+export * from './handoff/toolingBootstrap.js';
+export * from './handoff/coldStartQualification.js';

package/src/tooling/portable/input/node.input.js

@@ -0,0 +1,184 @@
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { zipBufferToImportEntries } from '../../../adapters/archive/archive.adapter.js';
+import { portableFinding } from '../findings.js';
+
+const DEFAULT_MAX_FILES = 4000;
+const DEFAULT_MAX_TEXT_BYTES = 4 * 1024 * 1024;
+const DEFAULT_EXCLUDED_DIRECTORIES = Object.freeze(['.git', 'node_modules', '.site-publish']);
+const TEXT_RE = /\.(?:md|markdown|json|txt|yml|yaml|js|mjs|cjs|ts|tsx|jsx|html|css)$/i;
+const PACKAGE_CONTROL_JSON_RE = /^tiinex\.package\/[^/]+\.json$/i;
+
+export async function loadNodePortableInput(targets, options = {}) {
+  const list = normalizeTargets(targets);
+  const files = [];
+  const findings = [];
+  const maxFiles = positiveInteger(options.maxFiles, DEFAULT_MAX_FILES);
+  const maxTextBytes = positiveInteger(options.maxTextBytes, DEFAULT_MAX_TEXT_BYTES);
+  if (!list.length) findings.push(portableFinding('error', 'portable.node.target.required', 'At least one file, directory, or zip target is required.'));
+
+  for (const target of list) {
+    if (files.length >= maxFiles) break;
+    const absolute = path.resolve(target);
+    let info;
+    try { info = await lstat(absolute); }
+    catch (error) {
+      findings.push(portableFinding('error', 'portable.node.target.unavailable', 'Input target could not be read.', { ref: target, detail: String(error.message || error) }));
+      continue;
+    }
+    if (info.isSymbolicLink()) {
+      findings.push(portableFinding('warning', 'portable.node.symlink.skipped', 'Symbolic-link input was skipped to avoid crossing the supplied material boundary.', { ref: target }));
+      continue;
+    }
+    if (info.isDirectory()) await readDirectory(absolute, files, findings, { ...options, maxFiles, maxTextBytes });
+    else if (info.isFile()) await readSingleFile(absolute, files, findings, { ...options, maxFiles, maxTextBytes });
+    else findings.push(portableFinding('warning', 'portable.node.target.unsupported', 'Input target is neither a regular file nor a directory and was skipped.', { ref: target }));
+  }
+
+  if (files.length >= maxFiles) findings.push(portableFinding('warning', 'portable.node.file-limit', 'Portable input stopped at the configured file limit.', { maxFiles }));
+  return Object.freeze({
+    files: Object.freeze(files.slice(0, maxFiles)),
+    findings: Object.freeze(findings),
+    sourceMode: 'portable-node-local'
+  });
+}
+
+async function readDirectory(root, files, findings, options) {
+  let entries;
+  try { entries = await walk(root, options, findings); }
+  catch (error) {
+    findings.push(portableFinding('error', 'portable.node.directory.read-failed', 'Directory input could not be traversed.', { ref: root, detail: String(error.message || error) }));
+    return;
+  }
+  for (const absolute of entries) {
+    if (files.length >= options.maxFiles) break;
+    await readSingleFile(absolute, files, findings, { ...options, root });
+  }
+}
+
+async function readSingleFile(absolute, files, findings, options = {}) {
+  if (files.length >= positiveInteger(options.maxFiles, DEFAULT_MAX_FILES)) return;
+  const relative = options.root ? path.relative(options.root, absolute) : path.basename(absolute);
+  const materialPath = relative.replace(/\\/g, '/');
+  let info;
+  try { info = await lstat(absolute); }
+  catch (error) {
+    findings.push(portableFinding('error', 'portable.node.file.unavailable', 'Input file could not be read.', { ref: materialPath, detail: String(error.message || error) }));
+    return;
+  }
+  if (info.isSymbolicLink()) {
+    findings.push(portableFinding('warning', 'portable.node.symlink.skipped', 'Symbolic-link material was skipped.', { ref: materialPath }));
+    return;
+  }
+
+  if (/\.zip$/i.test(absolute)) {
+    await readZipFile(absolute, files, findings, options);
+    return;
+  }
+  if (!TEXT_RE.test(absolute)) {
+    files.push(Object.freeze({ path: materialPath, size: info.size, type: '', kind: 'asset', sourceMode: 'portable-node-local', locator: Object.freeze({ kind: 'node-file', localPath: absolute }) }));
+    return;
+  }
+  if (info.size > positiveInteger(options.maxTextBytes, DEFAULT_MAX_TEXT_BYTES)) {
+    files.push(Object.freeze({ path: materialPath, size: info.size, type: 'text/plain', kind: 'asset', sourceMode: 'portable-node-local', locator: Object.freeze({ kind: 'node-file', localPath: absolute }) }));
+    findings.push(portableFinding('warning', 'portable.node.text-too-large', 'Text-like input exceeded the configured text limit and was retained as metadata only.', { ref: materialPath, size: info.size }));
+    return;
+  }
+  try {
+    files.push(Object.freeze({ path: materialPath, content: await readFile(absolute, 'utf8'), size: info.size, sourceMode: 'portable-node-local', locator: Object.freeze({ kind: 'node-file', localPath: absolute }) }));
+  } catch (error) {
+    findings.push(portableFinding('error', 'portable.node.file.read-failed', 'Text input could not be read.', { ref: materialPath, detail: String(error.message || error) }));
+  }
+}
+
+async function readZipFile(absolute, files, findings, options = {}) {
+  try {
+    const buffer = await readFile(absolute);
+    const result = await zipBufferToImportEntries(buffer, { source: 'portable-node-zip', excludeRepositoryInternals: true });
+    for (const entry of result.entries || []) {
+      if (files.length >= positiveInteger(options.maxFiles, DEFAULT_MAX_FILES)) break;
+      const maxTextBytes = positiveInteger(options.maxTextBytes, DEFAULT_MAX_TEXT_BYTES);
+      const packageControlContent = typeof entry.content !== 'string' && PACKAGE_CONTROL_JSON_RE.test(String(entry.path || '')) && Number(entry.size || 0) <= maxTextBytes && entry.bytes
+        ? new TextDecoder().decode(entry.bytes)
+        : null;
+      const textContent = typeof entry.content === 'string' ? entry.content : packageControlContent;
+      const tooLargeText = Boolean((typeof entry.content === 'string' || PACKAGE_CONTROL_JSON_RE.test(String(entry.path || ''))) && Number(entry.size || 0) > maxTextBytes);
+      if (tooLargeText) {
+        files.push(Object.freeze({ path: entry.path, size: entry.size, type: entry.type, kind: 'asset', sourceMode: 'portable-node-zip', locator: Object.freeze({ kind: 'node-zip-entry', archivePath: absolute, entryPath: entry.path }) }));
+        findings.push(portableFinding('warning', 'portable.node.zip-text-too-large', 'Zip text material exceeded the configured text limit and was retained as metadata only.', { ref: entry.path, size: entry.size }));
+      } else {
+        files.push(Object.freeze({
+          path: entry.path,
+          ...(typeof textContent === 'string' ? { content: textContent } : {}),
+          ...(typeof textContent !== 'string' && entry.bytes ? { data: entry.bytes } : {}),
+          size: entry.size,
+          type: entry.type,
+          kind: entry.kind,
+          sourceMode: 'portable-node-zip',
+          locator: Object.freeze({ kind: 'node-zip-entry', archivePath: absolute, entryPath: entry.path })
+        }));
+      }
+    }
+    findings.push(...(result.errors || []), ...(result.warnings || []));
+  } catch (error) {
+    findings.push(portableFinding('error', 'portable.node.zip.read-failed', 'Zip input could not be materialized.', { ref: absolute, detail: String(error.message || error) }));
+  }
+}
+
+async function walk(root, options = {}, findings = []) {
+  const out = [];
+  const excluded = new Set(options.excludeDirectories || DEFAULT_EXCLUDED_DIRECTORIES);
+  const excludedPathPrefixes = normalizeExcludedPathPrefixes(options.excludePathPrefixes);
+  const excludedPathRefs = new Set();
+  const queue = [root];
+  const maxFiles = positiveInteger(options.maxFiles, DEFAULT_MAX_FILES);
+  while (queue.length && out.length < maxFiles) {
+    const current = queue.shift();
+    let entries;
+    try { entries = await readdir(current, { withFileTypes: true }); }
+    catch (error) {
+      findings.push(portableFinding('warning', 'portable.node.directory.entry-unavailable', 'A directory entry could not be read and was skipped.', { ref: current, detail: String(error.message || error) }));
+      continue;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (excluded.has(entry.name)) continue;
+      const absolute = path.join(current, entry.name);
+      const relativePath = path.relative(root, absolute).replace(/\\/g, '/');
+      const excludedPrefix = excludedPathPrefixes.find((prefix) => relativePath === prefix.slice(0, -1) || relativePath.startsWith(prefix));
+      if (excludedPrefix) {
+        if (!excludedPathRefs.has(excludedPrefix)) {
+          excludedPathRefs.add(excludedPrefix);
+          findings.push(portableFinding('info', 'portable.node.directory.path-prefix-excluded', 'Configured directory material prefix was excluded from this read.', { ref: excludedPrefix.slice(0, -1) }));
+        }
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        findings.push(portableFinding('info', 'portable.node.symlink.skipped', 'Symbolic link was skipped during directory traversal.', { ref: relativePath }));
+        continue;
+      }
+      if (entry.isDirectory()) queue.push(absolute);
+      else if (entry.isFile()) out.push(absolute);
+      if (out.length >= maxFiles) break;
+    }
+  }
+  return out;
+}
+
+function normalizeExcludedPathPrefixes(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return list
+    .map((entry) => String(entry || '').replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, ''))
+    .filter(Boolean)
+    .map((entry) => `${entry}/`);
+}
+
+function normalizeTargets(targets) {
+  const list = Array.isArray(targets) ? targets : [targets];
+  return list.map((value) => String(value || '').trim()).filter(Boolean);
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number.parseInt(value, 10);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}

package/src/tooling/portable/input/portable.input.js

@@ -0,0 +1,249 @@
+import { classifyArchiveEntry, safeArchivePath } from '../../../adapters/archive/archive.adapter.js';
+import { createRecordFromMarkdown } from '../../../artifacts/artifact.record.js';
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+import { portableFinding } from '../findings.js';
+
+export const PORTABLE_INPUT_SCHEMA_ID = 'tiinex.portable.input.v1';
+
+export function normalizePortableInput(input = {}) {
+  const files = collectInputFiles(input);
+  const findings = [...(Array.isArray(input.findings) ? input.findings : [])];
+  const records = [];
+  const assets = [];
+  const workspaceEntries = [];
+  const seenPaths = new Set();
+
+  for (const [index, file] of files.entries()) {
+    const fallbackName = `material-${index + 1}.md`;
+    const materialPath = safeArchivePath(file.path || file.name || fallbackName);
+    if (!materialPath) {
+      findings.push(portableFinding('warning', 'portable.input.path.unsafe', 'Unsafe or empty material path was skipped.', { ref: file.path || file.name || '' }));
+      continue;
+    }
+    noteDuplicatePath(materialPath, seenPaths, findings);
+    const content = textContent(file);
+    const kind = file.kind || classifyArchiveEntry(materialPath, content || null);
+    const descriptor = Object.freeze({
+      path: materialPath,
+      kind,
+      size: Number(file.size || byteLengthOfText(content) || 0),
+      type: String(file.type || ''),
+      sourceMode: file.sourceMode || input.sourceMode || 'portable-local',
+      contentAvailable: Boolean(content || file.data || file.bytes || file.buffer),
+      locator: file.locator ? Object.freeze({ ...file.locator }) : null
+    });
+
+    if (kind === 'record' || kind === 'workspace') {
+      const record = recordFromFile(file, descriptor, content);
+      records.push(record);
+      if (kind === 'workspace') workspaceEntries.push(workspaceSummary(record));
+    } else {
+      assets.push(Object.freeze({ ...descriptor, previewState: content ? 'available' : 'metadata-only' }));
+    }
+  }
+
+  for (const [index, raw] of (Array.isArray(input.records) ? input.records : []).entries()) {
+    const record = normalizeExistingRecord(raw || {}, index);
+    noteDuplicatePath(record.path, seenPaths, findings);
+    records.push(record);
+  }
+  for (const asset of Array.isArray(input.assets) ? input.assets : []) assets.push(Object.freeze({ ...asset }));
+
+  const containsExplicitSourceMetadata = records.some((record) => isAcceptedRepositorySource(record.source) || (record.source?.adapterId && record.source.adapterId !== 'local'));
+  return Object.freeze({
+    schema: PORTABLE_INPUT_SCHEMA_ID,
+    boundary: Object.freeze({
+      mode: 'supplied-material',
+      remoteFetch: false,
+      remoteWrite: false,
+      inferredGitHubSource: false,
+      sourceInterpretation: 'explicit-only',
+      containsExplicitSourceMetadata
+    }),
+    files: Object.freeze(files.map((file, index) => fileSummary(file, index)).filter((file) => file.path)),
+    records: Object.freeze(records),
+    assets: Object.freeze(assets),
+    workspaceEntries: Object.freeze(workspaceEntries),
+    findings: Object.freeze(findings)
+  });
+}
+
+export function findSchemaMaterial(schemaId = '', input = {}) {
+  const wanted = String(schemaId || '').trim();
+  if (!wanted) return null;
+  const exactName = `${wanted}.schema.md`.toLowerCase();
+  const candidates = schemaCandidateMaterials(input);
+  let match = candidates.find((file) => normalizedPath(file).endsWith(exactName));
+  if (!match) {
+    match = candidates.find((file) => {
+      const materialPath = normalizedPath(file);
+      const content = textContent(file);
+      if (!materialPath.endsWith('.schema.md') || !content) return false;
+      try { return parseArtifactMarkdown(content).envelope?.current?.schema?.id === wanted; }
+      catch { return content.includes(wanted); }
+    });
+  }
+  if (!match) return null;
+  const materialPath = safeArchivePath(match.path || match.name || exactName);
+  const source = match.source || {};
+  const canonical = source.authority === 'canonical-core' && source.repository && (source.commit || source.ref);
+  return Object.freeze({
+    schemaId: wanted,
+    path: materialPath,
+    markdown: textContent(match),
+    role: canonical ? 'bundled-canonical-readable-schema-material' : 'supplied-readable-schema-material',
+    authority: canonical
+      ? `byte-bound canonical snapshot ${source.repository}@${source.commit || source.ref}`
+      : 'declared-by-material; verify against current Tiinex/docs',
+    source: canonical ? Object.freeze({
+      repository: source.repository,
+      commit: source.commit || source.ref,
+      path: source.path || materialPath,
+      qualification: source.qualification || 'bundled-byte-bound-canonical-snapshot'
+    }) : null
+  });
+}
+
+export function suppliedSchemaParentId(schemaId = '', input = {}) {
+  const material = findSchemaMaterial(schemaId, input);
+  if (!material?.markdown) return '';
+  try { return String(parseArtifactMarkdown(material.markdown).envelope?.parent?.schema?.id || '').trim(); }
+  catch { return ''; }
+}
+
+export function portableInputFiles(input = {}) {
+  return collectInputFiles(input);
+}
+
+function recordFromFile(file, descriptor, content) {
+  const derived = createRecordFromMarkdown(content, {
+    path: descriptor.path,
+    name: file.name || descriptor.path,
+    sourceMode: descriptor.sourceMode,
+    lifecycleStatus: file.lifecycleStatus || ''
+  });
+  return Object.freeze({
+    ...derived,
+    id: String(file.id || derived.id || descriptor.path),
+    source: normalizeSuppliedSource(file.source, descriptor.path),
+    locator: descriptor.locator ? Object.freeze({ ...descriptor.locator }) : null,
+    portableMaterialKind: descriptor.kind
+  });
+}
+
+function normalizeExistingRecord(raw = {}, index = 0) {
+  const materialPath = safeArchivePath(raw.path || raw.name || `record-${index + 1}.md`) || `record-${index + 1}.md`;
+  const content = textContent(raw);
+  const derived = content ? createRecordFromMarkdown(content, {
+    path: materialPath,
+    name: raw.name || materialPath,
+    sourceMode: raw.sourceMode || 'portable-local',
+    lifecycleStatus: raw.lifecycleStatus || ''
+  }) : {};
+  return Object.freeze({
+    ...derived,
+    ...raw,
+    id: String(raw.id || derived.id || materialPath),
+    path: materialPath,
+    markdown: typeof raw.markdown === 'string' ? raw.markdown : (typeof raw.content === 'string' ? raw.content : derived.markdown || ''),
+    sourceMode: raw.sourceMode || derived.sourceMode || 'portable-local',
+    source: normalizeSuppliedSource(raw.source, materialPath),
+    locator: raw.locator ? Object.freeze({ ...raw.locator }) : null,
+    portableMaterialKind: raw.portableMaterialKind || (raw.kind === 'workspace' ? 'workspace' : 'record')
+  });
+}
+
+function collectInputFiles(input = {}) {
+  const files = [];
+  if (typeof input.markdown === 'string') files.push({ path: input.path || 'attachment.md', content: input.markdown, sourceMode: input.sourceMode, source: input.source });
+  for (const file of Array.isArray(input.files) ? input.files : []) files.push(file || {});
+  return files;
+}
+
+function schemaCandidateMaterials(input = {}) {
+  const files = collectInputFiles(input);
+  for (const record of Array.isArray(input.records) ? input.records : []) {
+    if (typeof record?.markdown === 'string') files.push({ path: record.path || record.name || '', content: record.markdown, sourceMode: record.sourceMode, source: record.source });
+  }
+  return files;
+}
+
+function normalizeSuppliedSource(source = {}, materialPath = '') {
+  if (isAcceptedRepositorySource(source)) {
+    return Object.freeze({
+      repository: String(source.repository || ''),
+      ref: String(source.ref || ''),
+      commit: String(source.commit || ''),
+      path: safeArchivePath(source.path || materialPath) || materialPath,
+      authority: String(source.authority || 'remote-repository-unverified'),
+      remoteFetch: source.remoteFetch === true,
+      receiptQualification: 'accepted-host-repository-read',
+      provenanceQualification: source.commit ? 'accepted-host-repository-pinned' : 'accepted-host-repository-moving-ref',
+      ...(source.permalink ? { permalink: String(source.permalink) } : {}),
+      ...(source.durableLocator ? { durableLocator: String(source.durableLocator) } : {}),
+      boundary: source.boundary || 'Accepted host repository-read receipt material. Repository/ref/commit/path facts are preserved as receipt evidence only; portable input performs no remote fetch or provenance inference.'
+    });
+  }
+  if (source?.adapterId && source.adapterId !== 'local') {
+    return Object.freeze({
+      ...source,
+      path: source.path || materialPath,
+      boundary: source.boundary || 'Explicitly supplied source metadata; portable tooling did not fetch or infer this provenance.',
+      provenanceQualification: source.provenanceQualification || 'explicit-supplied-unverified'
+    });
+  }
+  return Object.freeze({
+    kind: source?.kind || 'local-session',
+    adapterId: source?.adapterId || 'local',
+    path: source?.path || materialPath,
+    boundary: source?.boundary || 'Portable local material; no GitHub provenance inferred.'
+  });
+}
+
+function isAcceptedRepositorySource(source = {}) {
+  return Boolean(
+    source
+    && source.receiptQualification === 'accepted-host-repository-read'
+    && /^accepted-host-repository-(?:pinned|moving-ref)$/.test(String(source.provenanceQualification || ''))
+    && source.repository
+    && source.path
+  );
+}
+
+function workspaceSummary(record = {}) {
+  return Object.freeze({ path: record.path, title: record.title, schemaId: record.schemaId, sourceMode: record.sourceMode });
+}
+
+function fileSummary(file = {}, index = 0) {
+  const materialPath = safeArchivePath(file.path || file.name || `material-${index + 1}`);
+  const content = textContent(file);
+  return Object.freeze({
+    path: materialPath,
+    size: Number(file.size || byteLengthOfText(content) || 0),
+    kind: file.kind || '',
+    type: String(file.type || ''),
+    contentAvailable: Boolean(content || file.data || file.bytes || file.buffer),
+    locator: file.locator ? Object.freeze({ ...file.locator }) : null
+  });
+}
+
+function noteDuplicatePath(materialPath, seenPaths, findings) {
+  if (!materialPath) return;
+  if (seenPaths.has(materialPath)) findings.push(portableFinding('warning', 'portable.input.path.duplicate', 'Duplicate material path is present; lineage matching may be ambiguous.', { ref: materialPath }));
+  seenPaths.add(materialPath);
+}
+
+function normalizedPath(file = {}) {
+  return String(safeArchivePath(file.path || file.name || '') || '').toLowerCase();
+}
+
+function textContent(file = {}) {
+  if (typeof file.content === 'string') return file.content;
+  if (typeof file.markdown === 'string') return file.markdown;
+  return '';
+}
+
+function byteLengthOfText(value = '') {
+  if (typeof Buffer !== 'undefined') return Buffer.byteLength(String(value || ''), 'utf8');
+  return new TextEncoder().encode(String(value || '')).byteLength;
+}

package/src/tooling/portable/lifecycle/lifecycle.action.js

@@ -0,0 +1,11 @@
+export function nextLifecycleAction({ readiness, retest, closure, blockers, missingEvidence, ambiguities, controllingTask }) {
+  const target = controllingTask?.path || controllingTask?.id || '';
+  if (closure.state === 'closed') return Object.freeze({ kind: 'none-unless-authoritatively-reopened', target, basis: 'qualified explicit closure after authoritative pass' });
+  if (closure.state === 'unresolved') return Object.freeze({ kind: 'repair-closure-qualification', target, basis: 'apparent closure exists but exact scope/pass basis/authority/currentness does not qualify' });
+  if (retest.state === 'unresolved') return Object.freeze({ kind: 'repair-retest-qualification', target, basis: 'apparent re-test exists but exact scope/method/coverage/authority/currentness does not qualify' });
+  if (readiness.state === 'unresolved') return Object.freeze({ kind: 'repair-lifecycle-evidence', target, basis: [...missingEvidence, ...ambiguities].slice(0, 6).map((item) => item.code).join(', ') || 'unresolved lifecycle evidence' });
+  if (retest.state === 'failed') return Object.freeze({ kind: 'address-failed-criteria-with-bounded-work', target, basis: 'authoritative current re-test failed' });
+  if (readiness.state === 'not-ready-for-retest') return Object.freeze({ kind: 'resolve-blocking-work-or-evidence', target: blockers[0]?.target || target, basis: blockers[0]?.code || 'qualified current blocker' });
+  if (retest.state === 'passed' && closure.state === 'open') return Object.freeze({ kind: 'obtain-explicit-authoritative-closure', target, basis: 'authoritative pass is qualified but no explicit closure governs the Task' });
+  return Object.freeze({ kind: 'invoke-authorized-retest', target, basis: 'derived readiness is ready-for-retest and no authoritative current outcome is observed' });
+}