@tiinex/core 0.1.1

package/src/schemas/workspace/tiinex.workspace.v1.schema.source.js

@@ -0,0 +1,9 @@
+import binding from './tiinex.workspace.v1.schema.json' with { type: 'json' };
+import projection from './tiinex.workspace.v1.schema.runtime.json' with { type: 'json' };
+import { defineBundledSchemaSource } from '../schema.source.js';
+
+export const schemaSource = defineBundledSchemaSource(binding, projection, Object.freeze({
+  bundledPath: 'src/schemas/workspace/tiinex.workspace.v1.schema.md',
+  sourceLabel: 'Viewer schema registry',
+  assetUrl: new URL('./tiinex.workspace.v1.schema.md', import.meta.url).href
+}));

package/src/schemas/workspace/tiinex.workspace.v1.sv.i18n.json

@@ -0,0 +1,7 @@
+{
+  "label": "Workspace",
+  "localBoundary": "Browser-local session state; no source files or GitHub provenance inferred.",
+  "emptyResult": "No artifacts yet — add local Markdown to get started. Click + (Add) or drop .md files here. Local files remain local/session only.",
+  "legacyEmptyResult": "No nodes match this view.",
+  "dropHint": "Add local Markdown via + (Add) or drop .md files here. For source-backed material use Add → GitHub source and provide explicit file paths."
+}

package/src/schemas/workspace/tiinex.workspace.v1.transitions.js

@@ -0,0 +1,10 @@
+export const workspaceTransitions = Object.freeze({
+  createLocal: 'create-workspace',
+  addManualFiles: 'add-manual-files',
+  addManualFolder: 'add-manual-folder',
+  addGitHubSource: 'add-github-source',
+  addExplicitUrls: 'add-explicit-urls',
+  closeSource: 'close-source',
+  closeWorkspace: 'close-workspace',
+  restoreFromHash: 'hash-restore'
+});

package/src/schemas/workspace/tiinex.workspace.v1.validate.js

@@ -0,0 +1,10 @@
+export function workspaceValidate(artifact = {}) {
+  const findings = [];
+  if (artifact?.envelope?.current?.schema?.id !== 'tiinex.workspace.v1') {
+    findings.push({ severity: 'warning', code: 'workspace.schema.mismatch', message: 'Workspace validator invoked for a non-workspace current schema.', source: 'tiinex.workspace.v1' });
+    return findings;
+  }
+  if (!artifact?.body?.title) findings.push({ severity: 'error', code: 'workspace.title.missing', message: 'Workspace artifact should begin with a human-readable display name.', source: 'tiinex.workspace.v1', fixability: 'safe' });
+  if (!String(artifact?.body?.text || '').trim()) findings.push({ severity: 'error', code: 'workspace.body.missing', message: 'Workspace artifact should contain a readable Markdown body.', source: 'tiinex.workspace.v1', fixability: 'manual' });
+  return findings;
+}

package/src/sources/github/github.issueTarget.js

@@ -0,0 +1,127 @@
+export const GITHUB_ISSUE_BODY_TARGET_KIND = 'github.issue.body';
+export const GITHUB_ISSUE_COMMENT_TARGET_KIND = 'github.issue.comment';
+
+const SAFE_PATH_SEGMENT = /^[A-Za-z0-9_.-]+$/;
+const WEB_ISSUE_LEXICAL = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/issues\/([1-9]\d*)(\/)?(?:#issuecomment-(\d+))?$/;
+const API_ISSUE_LEXICAL = /^https:\/\/api\.github\.com\/repos\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/issues\/([1-9]\d*)(\/)?$/;
+
+export function parseExactGithubIssueTarget(value = '') {
+  const raw = String(value || '');
+  if (!raw) return failure(raw, 'missing-github-issue-target');
+
+  const web = raw.match(WEB_ISSUE_LEXICAL);
+  if (web) return parseExactWebIssueTarget(raw, web);
+
+  const api = raw.match(API_ISSUE_LEXICAL);
+  if (api) return parseExactApiIssueTarget(raw, api);
+
+  return failure(raw, 'unsupported-github-issue-target');
+}
+
+export function githubIssueCommentIdFromTarget(value = '') {
+  const parsed = parseExactGithubIssueTarget(value);
+  return parsed.ok && parsed.targetKind === GITHUB_ISSUE_COMMENT_TARGET_KIND ? String(parsed.commentId || '') : '';
+}
+
+export function sameGithubRepository(a = '', b = '') {
+  const left = normalizeRepository(a);
+  const right = normalizeRepository(b);
+  return Boolean(left && right && left === right);
+}
+
+export function normalizeGithubRepository(value = '') {
+  return normalizeRepository(value);
+}
+
+function parseExactWebIssueTarget(raw, match) {
+  const owner = match[1];
+  const repo = match[2];
+  const issueNumber = match[3];
+  const trailingSlash = Boolean(match[4]);
+  const commentId = match[5] || '';
+  if (!validRepositoryParts(owner, repo) || !validIssueNumber(issueNumber)) return failure(raw, 'unsupported-github-issue-target');
+
+  const number = Number(issueNumber);
+  const issueTarget = `https://github.com/${owner}/${repo}/issues/${issueNumber}`;
+  return success({
+    raw,
+    repository: `${owner}/${repo}`,
+    owner,
+    repo,
+    number,
+    issueNumber,
+    commentId,
+    targetKind: commentId ? GITHUB_ISSUE_COMMENT_TARGET_KIND : GITHUB_ISSUE_BODY_TARGET_KIND,
+    inputTarget: commentId ? `${issueTarget}#issuecomment-${commentId}` : issueTarget,
+    issueTarget,
+    normalization: trailingSlash ? 'trailing-slash' : 'none'
+  });
+}
+
+function parseExactApiIssueTarget(raw, match) {
+  const owner = match[1];
+  const repo = match[2];
+  const issueNumber = match[3];
+  const trailingSlash = Boolean(match[4]);
+  if (!validRepositoryParts(owner, repo) || !validIssueNumber(issueNumber)) return failure(raw, 'unsupported-github-issue-target');
+
+  const number = Number(issueNumber);
+  const issueTarget = `https://github.com/${owner}/${repo}/issues/${issueNumber}`;
+  return success({
+    raw,
+    repository: `${owner}/${repo}`,
+    owner,
+    repo,
+    number,
+    issueNumber,
+    commentId: '',
+    targetKind: GITHUB_ISSUE_BODY_TARGET_KIND,
+    inputTarget: issueTarget,
+    issueTarget,
+    normalization: trailingSlash ? 'api-trailing-slash-to-canonical-web-issue' : 'api-issue-to-canonical-web-issue'
+  });
+}
+
+function validRepositoryParts(owner, repo) {
+  return Boolean(
+    owner && repo
+    && owner !== '.' && owner !== '..'
+    && repo !== '.' && repo !== '..'
+    && SAFE_PATH_SEGMENT.test(owner)
+    && SAFE_PATH_SEGMENT.test(repo)
+  );
+}
+
+function validIssueNumber(value = '') {
+  const lexical = String(value || '');
+  if (!/^[1-9]\d*$/.test(lexical)) return false;
+  const numeric = Number(lexical);
+  return Number.isSafeInteger(numeric) && String(numeric) === lexical;
+}
+
+function success(value = {}) {
+  return Object.freeze({
+    ok: true,
+    provider: 'github',
+    repository: value.repository,
+    owner: value.owner,
+    repo: value.repo,
+    number: value.number,
+    issueNumber: value.issueNumber,
+    commentId: value.commentId,
+    targetKind: value.targetKind,
+    inputTarget: value.inputTarget,
+    issueTarget: value.issueTarget,
+    mutable: true,
+    normalization: value.normalization || 'none'
+  });
+}
+
+function failure(input, error) {
+  return Object.freeze({ ok: false, input, error });
+}
+
+function normalizeRepository(value = '') {
+  const parts = String(value || '').trim().toLowerCase().split('/').filter(Boolean);
+  return parts.length === 2 ? `${parts[0]}/${parts[1]}` : '';
+}

package/src/sources/origin.references.js

@@ -0,0 +1,249 @@
+const ORIGIN_REFERENCE_SCHEMA = 'tiinex.origin.reference.v1';
+const ORIGIN_SOURCE_KIND = 'github.origin-reference';
+
+export function parseOriginReferenceValue(value = '') {
+  return normalizeOriginReference(value, { source: 'explicit-parse' });
+}
+
+export function collectOriginReferencesFromMarkdown(markdown = '') {
+  const refs = [];
+  const blocks = originBlocks(markdown);
+  for (const block of blocks) {
+    for (const candidate of originCandidatesFromBlock(block)) addOriginReference(refs, candidate, { source: 'continuity-origin' });
+  }
+  return refs;
+}
+
+export function originReferenceSourcesForRecords(records = []) {
+  const groups = new Map();
+  for (const record of Array.isArray(records) ? records : []) {
+    for (const ref of originReferencesForRecord(record)) {
+      if (!ref || ref.provider !== 'github' || !ref.repository) continue;
+      const key = ref.repository.toLowerCase();
+      if (!groups.has(key)) groups.set(key, makeGithubOriginSource(ref));
+      const source = groups.get(key);
+      source.originReferenceCount = Number(source.originReferenceCount || 0) + 1;
+      if (ref.kind === 'github-issue' && ref.url && !source.issueUrls.includes(ref.url)) source.issueUrls.push(ref.url);
+      if (ref.kind === 'github-file' && ref.path && !source.fileRefs.includes(ref.path)) source.fileRefs.push(ref.path);
+    }
+  }
+  return Array.from(groups.values()).map((source) => Object.freeze(Object.assign({}, source, {
+    count: 0,
+    config: Object.freeze(Object.assign({}, source.config, {
+      issueUrls: source.issueUrls.join('\n'),
+      fileRefs: source.fileRefs.join('\n')
+    }))
+  })));
+}
+
+export function upsertOriginReferenceSources(workspace = {}, records = []) {
+  const sources = originReferenceSourcesForRecords(records);
+  if (!sources.length) return [];
+  const existing = Array.isArray(workspace.sources) ? workspace.sources.slice() : [];
+  for (const source of sources) {
+    const index = existing.findIndex((item) => String(item?.id || '') === source.id);
+    if (index >= 0) {
+      const prior = existing[index];
+      const issueUrls = uniqueLines([prior.config?.issueUrls, source.config?.issueUrls].join('\n'));
+      const fileRefs = uniqueLines([prior.config?.fileRefs, source.config?.fileRefs].join('\n'));
+      existing[index] = Object.assign({}, prior, source, {
+        issueUrls,
+        fileRefs,
+        originReferenceCount: Number(prior.originReferenceCount || 0) + Number(source.originReferenceCount || 0),
+        config: Object.assign({}, prior.config || {}, source.config || {}, { issueUrls: issueUrls.join('\n'), fileRefs: fileRefs.join('\n') })
+      });
+    } else {
+      existing.push(Object.assign({}, source));
+    }
+  }
+  workspace.sources = existing;
+  workspace.sourceOrder = existing.map((item) => item.id);
+  return sources;
+}
+
+export function originReferencesForRecord(record = {}) {
+  const refs = [];
+  for (const ref of Array.isArray(record.originReferences) ? record.originReferences : []) addOriginReference(refs, ref.value || ref.url || ref.path || '', { source: ref.source || 'record.originReferences' });
+  for (const value of [record.origin, record.parentOrigin, record.sourceTarget?.parentRawUrl, record.sourceTarget?.parentSourceUrl, record.snapshot?.parentRawUrl, record.snapshot?.parentSourceUrl]) addOriginReference(refs, value, { source: 'record.explicit-origin' });
+  return refs;
+}
+
+export function recoverySourceForRecord(record = {}, workspace = {}) {
+  const direct = record?.source || {};
+  if (isGithubConfiguredSource(direct)) return Object.assign({}, direct, { ref: direct.ref || direct.config?.ref || '' });
+  const refs = originReferencesForRecord(record).filter((ref) => ref.provider === 'github' && ref.repository);
+  if (!refs.length) return null;
+  const repo = refs[0].repository;
+  const workspaceSource = (Array.isArray(workspace?.sources) ? workspace.sources : []).find((source) => {
+    const sourceRepo = String(source.repo || source.repository || source.config?.repo || '').trim().toLowerCase();
+    return sourceRepo && sourceRepo === repo.toLowerCase() && isGithubConfiguredSource(source);
+  });
+  if (workspaceSource) return Object.assign({}, workspaceSource, { ref: workspaceSource.ref || workspaceSource.config?.ref || '' });
+  return makeGithubOriginSource(refs[0]);
+}
+
+export function githubIssueUrlsForRecord(record = {}) {
+  return uniqueLines(originReferencesForRecord(record).filter((ref) => ref.kind === 'github-issue').map((ref) => ref.url));
+}
+
+export function githubFileRefsForRecord(record = {}) {
+  return uniqueLines(originReferencesForRecord(record).filter((ref) => ref.kind === 'github-file').map((ref) => ref.path));
+}
+
+export function isOriginReferenceSource(source = {}) {
+  return source.originReferenceSource === true || source.sourceKind === ORIGIN_SOURCE_KIND;
+}
+
+function makeGithubOriginSource(ref = {}) {
+  const repo = ref.repository || `${ref.owner || 'owner'}/${ref.repo || 'repo'}`;
+  const id = `origin:github:${repo.toLowerCase().replace(/[^a-z0-9/_-]+/g, '-').replace(/\//g, ':')}`;
+  const sourceRef = String(ref.ref || '').trim();
+  return {
+    id,
+    kind: 'github-tree',
+    adapterId: 'github',
+    sourceKind: ORIGIN_SOURCE_KIND,
+    label: `GitHub origin · ${repo}`,
+    roleLabel: 'recovery only',
+    countLabel: 'origin refs',
+    repo,
+    repository: repo,
+    ref: sourceRef,
+    rootPath: '.topics',
+    config: { repo, ref: sourceRef, rootPath: '.topics', issueUrls: '', fileRefs: '' },
+    count: 0,
+    sourceBacked: false,
+    originReferenceSource: true,
+    recoveryOnly: true,
+    closeable: true,
+    discoveryState: 'deferred',
+    issueUrls: [],
+    fileRefs: [],
+    boundary: 'explicit GitHub origin reference recovered from imported artifacts; recovery only for lineage lookup, imported material remains browser-local/session',
+    transportLabel: 'Origin recovery only',
+    loadable: false,
+    transportRefreshTier: 'direct'
+  };
+}
+
+function originBlocks(markdown = '') {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const blocks = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = lines[i].match(/^(\s*)-\s*Origin:\s*(.*)$/i);
+    if (!match) continue;
+    const indent = match[1].length;
+    const inline = match[2].trim();
+    const collected = [];
+    if (inline) collected.push(inline);
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const line = lines[j];
+      const top = line.match(/^(\s*)-\s+\S/);
+      if (top && top[1].length <= indent) break;
+      if (line.trim()) collected.push(line.trim());
+    }
+    if (collected.length) blocks.push(collected.join('\n'));
+  }
+  return blocks;
+}
+
+function originCandidatesFromBlock(block = '') {
+  const out = [];
+  for (const line of String(block || '').split('\n')) {
+    const item = line.replace(/^[-*]\s+/, '').trim();
+    if (!item) continue;
+    const labelled = item.match(/^([A-Za-z][A-Za-z0-9 _+-]{0,40}):\s*(.+)$/);
+    const value = labelled ? labelled[2].trim() : item;
+    out.push(value);
+    for (const link of markdownLinks(item)) out.push(link.href || link.label || '');
+  }
+  return out;
+}
+
+function addOriginReference(refs = [], value = '', meta = {}) {
+  const normalized = normalizeOriginReference(value, meta);
+  if (!normalized) return;
+  const key = `${normalized.kind}:${normalized.url || normalized.path || normalized.value}`.toLowerCase();
+  if (refs.some((item) => `${item.kind}:${item.url || item.path || item.value}`.toLowerCase() === key)) return;
+  refs.push(normalized);
+}
+
+function normalizeOriginReference(value = '', meta = {}) {
+  const raw = stripMarkdown(String(value || '').trim());
+  if (!raw) return null;
+  const github = githubReference(raw);
+  if (github) return Object.freeze(Object.assign({ schema: ORIGIN_REFERENCE_SCHEMA, value: raw, explicit: true, source: meta.source || 'origin' }, github));
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(raw)) return Object.freeze({ schema: ORIGIN_REFERENCE_SCHEMA, kind: 'url', value: raw, url: raw, explicit: true, source: meta.source || 'origin' });
+  return Object.freeze({ schema: ORIGIN_REFERENCE_SCHEMA, kind: 'relative', value: raw, path: normalizePath(raw), explicit: true, source: meta.source || 'origin' });
+}
+
+function githubReference(value = '') {
+  try {
+    const url = new URL(value);
+    const host = url.hostname.toLowerCase();
+    const parts = url.pathname.split('/').filter(Boolean);
+    if ((host === 'github.com' || host.endsWith('.github.com')) && parts.length >= 4 && ['issues', 'discussions', 'pull'].includes(parts[2])) {
+      const commentId = url.hash.match(/(?:issuecomment-|discussioncomment-)(\d+)/i)?.[1] || '';
+      return { kind: 'github-issue', provider: 'github', owner: parts[0], repo: parts[1], repository: `${parts[0]}/${parts[1]}`, surface: parts[2], number: parts[3], commentId, url: canonicalGithubIssueUrl(value) };
+    }
+    if (host === 'raw.githubusercontent.com' && parts.length >= 4) {
+      return { kind: 'github-file', provider: 'github', owner: parts[0], repo: parts[1], repository: `${parts[0]}/${parts[1]}`, ref: parts[2], path: normalizePath(parts.slice(3).join('/')), url: value };
+    }
+    if ((host === 'github.com' || host.endsWith('.github.com')) && parts.length >= 5 && parts[2] === 'blob') {
+      return { kind: 'github-file', provider: 'github', owner: parts[0], repo: parts[1], repository: `${parts[0]}/${parts[1]}`, ref: parts[3], path: normalizePath(parts.slice(4).join('/')), url: value };
+    }
+  } catch (_) {}
+  return null;
+}
+
+function canonicalGithubIssueUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    const hash = url.hash.match(/(?:issuecomment-|discussioncomment-)(\d+)/i)?.[0] || '';
+    if ((url.hostname === 'github.com' || url.hostname.endsWith('.github.com')) && parts.length >= 4) return `https://github.com/${parts[0]}/${parts[1]}/${parts[2]}/${parts[3]}${hash ? `#${hash}` : ''}`;
+  } catch (_) {}
+  return String(value || '').trim();
+}
+
+function markdownLinks(value = '') {
+  const out = [];
+  const re = /\[([^\]]+)\]\(([^)]+)\)/g;
+  let match;
+  while ((match = re.exec(String(value || '')))) out.push({ label: match[1].trim(), href: match[2].trim() });
+  return out;
+}
+
+function stripMarkdown(value = '') {
+  const link = String(value || '').trim().match(/^\[([^\]]+)\]\(([^)]+)\)$/);
+  return (link ? link[2] : String(value || '')).trim();
+}
+
+function normalizePath(value = '') {
+  const out = [];
+  for (const part of String(value || '').replace(/\\/g, '/').split('/')) {
+    const clean = part.trim();
+    if (!clean || clean === '.') continue;
+    if (clean === '..') out.pop();
+    else out.push(clean);
+  }
+  return out.join('/');
+}
+
+function uniqueLines(value = '') {
+  const items = Array.isArray(value) ? value : String(value || '').split(/\r?\n|,/);
+  const seen = new Set();
+  const out = [];
+  for (const item of items.map((entry) => String(entry || '').trim()).filter(Boolean)) {
+    const key = item.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+function isGithubConfiguredSource(source = {}) {
+  const adapter = String(source.adapterId || source.sourceKind || source.kind || '').toLowerCase();
+  return adapter.includes('github') || Boolean(source.repo || source.repository || source.config?.repo);
+}

package/src/sources/source.explicitTargets.js

@@ -0,0 +1,49 @@
+export function normalizeExplicitFileRefs(value = []) {
+  const items = Array.isArray(value) ? value : String(value || '').split(/\r?\n/);
+  const out = [];
+  const seen = new Set();
+  for (const item of items) {
+    const ref = String(item?.ref ?? item ?? '').trim();
+    if (!ref || seen.has(ref)) continue;
+    seen.add(ref);
+    out.push(ref);
+  }
+  return Object.freeze(out);
+}
+
+export function explicitFileRefsText(value = []) {
+  return normalizeExplicitFileRefs(value).join('\n');
+}
+
+export const WEB_MARKDOWN_SOURCE_TARGET_KIND = 'web.markdown';
+
+export function normalizeExternalWebArtifactUrl(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  try {
+    const url = new URL(raw);
+    return /^https?:$/i.test(url.protocol) ? url.href : '';
+  } catch (_) { return ''; }
+}
+
+export function explicitWebArtifactSourceTarget(inputTarget = '', materializedTarget = '') {
+  const input = normalizeExternalWebArtifactUrl(inputTarget);
+  const raw = normalizeExternalWebArtifactUrl(materializedTarget || inputTarget);
+  if (!input || !raw) return null;
+  return Object.freeze({ targetKind: WEB_MARKDOWN_SOURCE_TARGET_KIND, inputTarget: input, rawUrl: raw });
+}
+
+export function externalWebArtifactUrl(record = {}) {
+  const source = record?.source || {};
+  const target = record?.sourceTarget || {};
+  const mode = String(record?.sourceMode || '').toLowerCase();
+  const adapterId = String(source.adapterId || '').toLowerCase();
+  const sourceKind = String(source.sourceKind || source.kind || '').toLowerCase();
+  const targetKind = String(target.targetKind || '').toLowerCase();
+  const webShaped = targetKind === WEB_MARKDOWN_SOURCE_TARGET_KIND
+    || sourceKind === WEB_MARKDOWN_SOURCE_TARGET_KIND
+    || (adapterId === 'web' && sourceKind.includes('web'))
+    || (mode === 'explicit-url' && targetKind === WEB_MARKDOWN_SOURCE_TARGET_KIND);
+  if (!webShaped) return '';
+  return normalizeExternalWebArtifactUrl(target.inputTarget || source.url || target.rawUrl || '');
+}

package/src/sources/transport.levels.js

@@ -0,0 +1,107 @@
+export const TRANSPORT_LEVELS_SCHEMA_ID = 'tiinex.transport.levels.v1';
+export const TRANSPORT_PLAN_SCHEMA_ID = 'tiinex.transport.operationPlan.v1';
+
+export const TransportLevel = Object.freeze({
+  TL0: 'TL0',
+  TL1: 'TL1',
+  TL2: 'TL2',
+  TL3: 'TL3',
+  TL4: 'TL4'
+});
+
+const LEVEL_ORDER = Object.freeze([TransportLevel.TL0, TransportLevel.TL1, TransportLevel.TL2, TransportLevel.TL3, TransportLevel.TL4]);
+const OPERATION_ALIASES = Object.freeze({
+  readKnown: 'read-known',
+  listScope: 'list-scope',
+  readHistory: 'read-history',
+  localDownload: 'local-download',
+  localImport: 'local-import',
+  write: 'write',
+  verify: 'verify',
+  sync: 'sync'
+});
+
+export function normalizeTransportLevel(value = '') {
+  const text = String(value || '').trim().toUpperCase();
+  return LEVEL_ORDER.includes(text) ? text : '';
+}
+
+export function transportLevelRank(level = '') {
+  const normalized = normalizeTransportLevel(level);
+  return normalized ? LEVEL_ORDER.indexOf(normalized) : -1;
+}
+
+export function transportLevelsAtOrBelow(level = '') {
+  const rank = transportLevelRank(level);
+  if (rank < 0) return Object.freeze([]);
+  return Object.freeze(LEVEL_ORDER.slice(0, rank + 1));
+}
+
+export function normalizeTransportOperation(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  return OPERATION_ALIASES[raw] || raw.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`).replace(/^-/, '').toLowerCase();
+}
+
+export function resolveTransportPlan(sourceConfig = {}, operation = '', input = {}) {
+  const op = normalizeTransportOperation(operation || input.operation || 'read-known');
+  const configured = configuredLevelForOperation(sourceConfig, op) || normalizeTransportLevel(input.defaultLevel || TransportLevel.TL0) || TransportLevel.TL0;
+  const requested = normalizeTransportLevel(input.requestedLevel || configured) || configured;
+  const maxRank = transportLevelRank(configured);
+  const requestedRank = transportLevelRank(requested);
+  const selected = requestedRank >= 0 && requestedRank <= maxRank ? requested : configured;
+  const fallbackLevels = input.allowFallback === false ? Object.freeze([]) : transportLevelsAtOrBelow(selected).filter((level) => level !== selected).reverse();
+  const credentialMaterialIncluded = hasCredentialMaterial(sourceConfig);
+  const authRequired = transportLevelRank(selected) >= transportLevelRank(TransportLevel.TL3) || Boolean(sourceConfig.authRequired || input.authRequired);
+  return deepFreeze({
+    schema: TRANSPORT_PLAN_SCHEMA_ID,
+    operation: op,
+    selectedLevel: selected,
+    configuredLevel: configured,
+    fallbackLevels,
+    authRequired,
+    authProvider: String(sourceConfig.authProvider || input.authProvider || '').trim(),
+    credentialMaterialIncluded,
+    status: credentialMaterialIncluded ? 'blocked' : 'ready',
+    boundary: 'Transport plan describes allowed movement for one operation. It must not infer provenance, mutate sources, or include user secrets in artifacts, source config, or export packages.'
+  });
+}
+
+function configuredLevelForOperation(sourceConfig = {}, operation = '') {
+  const candidates = [
+    sourceConfig.transportLevels?.[operation],
+    sourceConfig.transportLevels?.[operation.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase())],
+    sourceConfig.operations?.[operation]?.transportLevel,
+    sourceConfig.capabilities?.[operation]?.transportLevel,
+    sourceConfig.transportLevel,
+    sourceConfig.configuredTransportLevel
+  ];
+  for (const candidate of candidates) {
+    const normalized = normalizeTransportLevel(candidate);
+    if (normalized) return normalized;
+  }
+  return '';
+}
+
+function hasCredentialMaterial(value = {}) {
+  const secretKeys = /(?:token|password|passwd|secret|api[_-]?key|refresh[_-]?token|access[_-]?token|client[_-]?secret)/i;
+  const stack = [value];
+  const seen = new Set();
+  while (stack.length) {
+    const item = stack.pop();
+    if (!item || typeof item !== 'object' || seen.has(item)) continue;
+    seen.add(item);
+    for (const [key, child] of Object.entries(item)) {
+      if (secretKeys.test(key) && child != null && String(child).trim()) return true;
+      if (child && typeof child === 'object') stack.push(child);
+    }
+  }
+  return false;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}

package/src/tooling/portable/adapters/cli/cli.cold-start-input.js

@@ -0,0 +1,34 @@
+import { readFile } from 'node:fs/promises';
+import { loadNodePortableInput } from '../../input/node.input.js';
+
+export async function prepareQualifyColdStartCommandInput(parsed, flags = {}) {
+  const evidenceFile = flags.evidence || flags.trace || flags.input || '';
+  if (evidenceFile) {
+    const evidence = JSON.parse(await readFile(evidenceFile, 'utf8'));
+    return { input: { ...evidence, ingressKind: flags.ingress || evidence.ingressKind || evidence.kind || 'routed-handoff-package' }, options: {} };
+  }
+  const packagePath = String(flags.package || parsed.positionals[0] || '').trim();
+  if (!packagePath) throw new Error('portable.cli.cold-start-package-or-evidence.required');
+  const material = await loadNodePortableInput([packagePath], { maxFiles: flags['max-files'], maxTextBytes: flags['max-text-bytes'] });
+  const interaction = await readOptionalJson(flags.interaction);
+  return {
+    input: {
+      ...material,
+      bundle: material,
+      ingressKind: flags.ingress || flags.kind || 'routed-handoff-package',
+      route: flags.route || '',
+      packageSourcePath: packagePath,
+      preTakeover: flags['pre-takeover'] || 'unverified',
+      hostEvidenceSource: flags['evidence-source'] || '',
+      interaction: interaction.interaction || interaction,
+      holderBinding: { roleLabel: flags['holder-role'] || '', holderId: flags['holder-id'] || '' },
+      toolingAvailable: flags['tooling-unavailable'] ? false : true
+    },
+    options: {}
+  };
+}
+
+async function readOptionalJson(file) {
+  if (!file) return {};
+  return JSON.parse(await readFile(file, 'utf8'));
+}