@tiinex/core 0.1.1

package/src/tooling/portable/adapters/llm/llm.entrypoint.js

@@ -0,0 +1,34 @@
+import { listPortableOperations, runPortableOperation } from '../../operation.catalog.js';
+import { openPortableSession, restorePortableSession } from '../../session/portable.session.js';
+
+export const TIINEX_LLM_ENTRYPOINT_SCHEMA_ID = 'tiinex.llm.entrypoint.v1';
+
+export function openTiinexLlmSession(input = {}) {
+  return openPortableSession(input);
+}
+
+export function restoreTiinexLlmSession(snapshot = {}) {
+  return restorePortableSession(snapshot);
+}
+
+export async function runTiinexLlmOperation(operation, input = {}, options = {}) {
+  return runPortableOperation(operation, input, options);
+}
+
+export function describeTiinexLlmEntrypoint() {
+  return Object.freeze({
+    schema: TIINEX_LLM_ENTRYPOINT_SCHEMA_ID,
+    boundary: Object.freeze({
+      material: 'supplied attachments, project sources, or explicit records',
+      sourceProvenance: 'explicit-only; local material is never guessed as GitHub-backed',
+      remoteFetch: 'host-mediated only through explicit provider adapters or provider-response handoff',
+      remoteWrite: false,
+      sourceMutation: false,
+      receivedCodeExecution: false,
+      toolingDiscovery: 'capability-level with ranked concrete host-tool bindings and explicit normalized receipts; product-specific names are optional inputs, not semantic authority',
+      unknownSchemaResolution: 'loaded/cache/provider response first; otherwise self-describing host request'
+    }),
+    operations: listPortableOperations().operations,
+    bootstrap: 'src/tooling/portable/bootstrap/tiinex.llm.bootstrap.md'
+  });
+}

package/src/tooling/portable/adapters/node/checkpoint.verify.js

@@ -0,0 +1,267 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { access, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { listPortableOperations } from '../../operation.catalog.js';
+import {
+  PORTABLE_VALIDATION_RECEIPT_SCHEMA_ID,
+  describePortableCheckpointGate,
+  qualifyPortableCheckpoint
+} from '../../conformance/checkpoint.qualification.js';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_REPO_ROOT = path.resolve(MODULE_DIR, '../../../../..');
+
+export async function runNodePortableCheckpointVerification(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot || DEFAULT_REPO_ROOT);
+  const profile = options.profile || 'source-clean';
+  const gate = describePortableCheckpointGate({ profile });
+  const packageJson = JSON.parse(await readFile(path.join(repoRoot, 'package.json'), 'utf8'));
+  const workflowText = await readOptional(path.join(repoRoot, '.github/workflows/publish-public.yml'));
+  const parityText = await readOptional(path.join(repoRoot, 'src/parity/poc.parityLedger.js'));
+  const portableFiles = await collectPortableSourceFiles(repoRoot);
+  const portableIdentity = await buildPortableIdentity(repoRoot, portableFiles);
+  const lockfiles = await existingPaths(repoRoot, ['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml']);
+  const installer = extractInstaller(workflowText);
+  const parityCheckpoint = extractParityCheckpoint(parityText);
+  const receipts = [];
+
+  for (const descriptor of gate.gates) {
+    const receipt = descriptor.id === 'portable-syntax'
+      ? await runSyntaxGate(repoRoot, portableFiles, descriptor, options)
+      : await runCommandGate(repoRoot, descriptor, options);
+    receipts.push(receipt);
+    if (options.failFast && receipt.status === 'failed') break;
+  }
+
+  const qualification = qualifyPortableCheckpoint({
+    profile,
+    siteIdentity: {
+      name: packageJson.name,
+      version: packageJson.version,
+      description: packageJson.description,
+      commit: options.commit || '',
+      sourceCheckpoint: options.sourceCheckpoint || ''
+    },
+    portableIdentity,
+    receipts,
+    reproducibility: {
+      dependencies: packageJson.dependencies || {},
+      lockfiles,
+      installer
+    },
+    continuity: {
+      parityCheckpoint,
+      expectedVersion: options.expectedVersion || ''
+    },
+    evidence: options.evidence || []
+  });
+
+  const result = Object.freeze({
+    schema: 'tiinex.portable.node-checkpoint-verification.v1',
+    generatedAt: new Date().toISOString(),
+    repoRoot: options.includePaths === true ? repoRoot : '.',
+    profile,
+    receipts: Object.freeze(receipts),
+    qualification
+  });
+  if (options.output) await writeFile(path.resolve(repoRoot, options.output), `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  return result;
+}
+
+async function runSyntaxGate(repoRoot, files, descriptor, options) {
+  const startedAt = new Date();
+  const details = [];
+  let failed = false;
+  for (const relativePath of files.filter((file) => /\.(?:js|mjs)$/i.test(file))) {
+    const result = await runProcess(repoRoot, process.execPath, ['--check', relativePath], options);
+    details.push({ path: relativePath, exitCode: result.exitCode, status: result.exitCode === 0 ? 'passed' : 'failed', stderrDigest: digest(result.stderr) });
+    if (result.exitCode !== 0) failed = true;
+  }
+  const finishedAt = new Date();
+  return receipt(descriptor, {
+    status: failed ? 'failed' : 'passed',
+    exitCode: failed ? 1 : 0,
+    startedAt,
+    finishedAt,
+    stdout: `${details.filter((entry) => entry.status === 'passed').length}/${details.length} portable JavaScript sources passed node --check`,
+    stderr: '',
+    details
+  });
+}
+
+async function runCommandGate(repoRoot, descriptor, options) {
+  const startedAt = new Date();
+  if (descriptor.requiresInstalledDependencies && !(await exists(path.join(repoRoot, 'node_modules')))) {
+    const canUseNoInstallTsc = descriptor.id === 'typecheck' && await commandAvailable(repoRoot, 'npx', ['--no-install', 'tsc', '--version']);
+    if (!canUseNoInstallTsc) {
+      const finishedAt = new Date();
+      return receipt(descriptor, {
+        status: 'blocked',
+        exitCode: null,
+        reason: 'installed-dependencies-unavailable',
+        startedAt,
+        finishedAt,
+        stdout: '',
+        stderr: 'node_modules is unavailable for a dependency-backed checkpoint gate.'
+      });
+    }
+  }
+  const parsed = splitCommand(descriptor.command);
+  const result = await runProcess(repoRoot, parsed.command, parsed.args, options);
+  const finishedAt = new Date();
+  return receipt(descriptor, {
+    status: result.spawnError ? 'blocked' : result.exitCode === 0 ? 'passed' : 'failed',
+    exitCode: result.spawnError ? null : result.exitCode,
+    reason: result.spawnError ? 'command-unavailable' : '',
+    startedAt,
+    finishedAt,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    details: result.spawnError ? { message: result.spawnError.message } : null
+  });
+}
+
+function receipt(descriptor, input) {
+  return Object.freeze({
+    schema: PORTABLE_VALIDATION_RECEIPT_SCHEMA_ID,
+    gateId: descriptor.id,
+    command: descriptor.command,
+    status: input.status,
+    exitCode: input.exitCode,
+    reason: input.reason || '',
+    startedAt: input.startedAt.toISOString(),
+    finishedAt: input.finishedAt.toISOString(),
+    durationMs: input.finishedAt.getTime() - input.startedAt.getTime(),
+    stdoutDigest: digest(input.stdout),
+    stderrDigest: digest(input.stderr),
+    outputSummary: summarizeOutput(input.stdout, input.stderr),
+    details: input.details || null,
+    environment: Object.freeze({ node: process.version, platform: process.platform, arch: process.arch })
+  });
+}
+
+async function runProcess(cwd, command, args, options = {}) {
+  return await new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const child = spawn(command, args, {
+      cwd,
+      env: { ...process.env, CI: process.env.CI || '1', NO_COLOR: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: false
+    });
+    child.stdout.on('data', (chunk) => {
+      stdout += String(chunk);
+      if (options.echo === true) process.stdout.write(chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += String(chunk);
+      if (options.echo === true) process.stderr.write(chunk);
+    });
+    child.on('error', (spawnError) => {
+      if (settled) return;
+      settled = true;
+      resolve({ exitCode: null, stdout, stderr, spawnError });
+    });
+    child.on('close', (exitCode) => {
+      if (settled) return;
+      settled = true;
+      resolve({ exitCode: typeof exitCode === 'number' ? exitCode : 1, stdout, stderr, spawnError: null });
+    });
+  });
+}
+
+async function buildPortableIdentity(repoRoot, files) {
+  const sourceHash = createHash('sha256');
+  for (const relativePath of files) {
+    sourceHash.update(relativePath);
+    sourceHash.update('\0');
+    sourceHash.update(await readFile(path.join(repoRoot, relativePath)));
+    sourceHash.update('\0');
+  }
+  const operations = listPortableOperations().operations;
+  const operationFingerprint = digest(JSON.stringify(operations));
+  const bootstrapPath = 'src/tooling/portable/bootstrap/tiinex.llm.bootstrap.md';
+  const bootstrap = await readOptional(path.join(repoRoot, bootstrapPath));
+  return Object.freeze({
+    sourceFingerprint: `sha256:${sourceHash.digest('hex')}`,
+    operationFingerprint,
+    operationCount: operations.length,
+    sourceFiles: files.length,
+    bootstrapFingerprint: bootstrap ? digest(bootstrap) : ''
+  });
+}
+
+async function collectPortableSourceFiles(repoRoot) {
+  const roots = [
+    'src/tooling/portable',
+    'tools/tiinex-portable.mjs',
+    'tools/tiinex-portable-verify.mjs',
+    'docs/architecture/portable-tooling-entrypoints.md'
+  ];
+  const files = [];
+  for (const root of roots) {
+    const absolute = path.join(repoRoot, root);
+    if (!(await exists(absolute))) continue;
+    const info = await stat(absolute);
+    if (info.isFile()) files.push(root);
+    else files.push(...await walkFiles(repoRoot, absolute));
+  }
+  return [...new Set(files)].sort();
+}
+
+async function walkFiles(repoRoot, directory) {
+  const out = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const absolute = path.join(directory, entry.name);
+    if (entry.isDirectory()) out.push(...await walkFiles(repoRoot, absolute));
+    else if (entry.isFile()) out.push(path.relative(repoRoot, absolute).replace(/\\/g, '/'));
+  }
+  return out;
+}
+
+async function existingPaths(repoRoot, names) {
+  const out = [];
+  for (const name of names) if (await exists(path.join(repoRoot, name))) out.push(name);
+  return out;
+}
+
+async function exists(target) {
+  try { await access(target); return true; }
+  catch { return false; }
+}
+
+async function readOptional(target) {
+  try { return await readFile(target, 'utf8'); }
+  catch { return ''; }
+}
+
+async function commandAvailable(cwd, command, args) {
+  const result = await runProcess(cwd, command, args, {});
+  return !result.spawnError && result.exitCode === 0;
+}
+
+function extractInstaller(workflow = '') {
+  const match = String(workflow || '').match(/run:\s*(npm\s+(?:install|ci)[^\n]*)/i);
+  return match?.[1]?.trim() || '';
+}
+
+function extractParityCheckpoint(source = '') {
+  const match = String(source || '').match(/checkpoint:\s*['"]([^'"]+)['"]/);
+  return match?.[1]?.trim() || '';
+}
+
+function splitCommand(commandLine = '') {
+  const tokens = String(commandLine || '').match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+  return { command: tokens.shift() || '', args: tokens.map((token) => token.replace(/^"|"$/g, '')) };
+}
+
+function digest(value = '') { return `sha256:${createHash('sha256').update(String(value || '')).digest('hex')}`; }
+function summarizeOutput(stdout = '', stderr = '') {
+  const text = `${stdout}\n${stderr}`.trim().replace(/\s+/g, ' ');
+  return text.length <= 320 ? text : `${text.slice(0, 317)}...`;
+}

package/src/tooling/portable/adapters/node/handoff.manufacture.bootstrap.js

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sha256Hex } from '../../../../export/package.bytes.js';
+
+export const PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_SCHEMA_ID = 'tiinex.portable.tooling-bootstrap.manifest.v1';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_RUNTIME_ROOT = path.resolve(MODULE_DIR, '../../../../..');
+const IMPORT_RE = /(?:\bimport\s+(?:[^'";]+?\s+from\s+)?|\bexport\s+(?:\*|\{[^}]*\})\s+from\s+|\bimport\s*\()\s*['"]([^'"]+)['"]/g;
+
+export async function buildToolingBootstrapTransportFiles(input = {}) {
+  const delivery = normalizeDelivery(input.delivery);
+  const runtimeRoot = path.resolve(String(input.runtimeRoot || DEFAULT_RUNTIME_ROOT));
+  const runtime = await enumerateRuntimeDependencyGraph(runtimeRoot, { maxFiles: input.maxFiles });
+  const manifest = Object.freeze({
+    schema: PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_SCHEMA_ID,
+    version: 1,
+    delivery,
+    entrypoint: 'runtime/tools/tiinex-portable.mjs',
+    qualification: Object.freeze({ authority: 'manifest-declared-exact-runtime-bytes-only', ordinaryWorkspaceBytesAreBootstrapAuthority: false, filenameOrColocationAuthority: false }),
+    runtime: Object.freeze({ files: runtime.entries.length, bytes: runtime.totalBytes, representationSha256: runtime.representationSha256, entries: Object.freeze(runtime.entries.map(({ path: entryPath, bytes, sha256 }) => Object.freeze({ path: `runtime/${entryPath}`, bytes, sha256 }))) }),
+    canonicalSchemaMaterial: Object.freeze({ boundary: 'Carried as runtime data required by the portable schema provider; canonical schema authority remains the declared external Tiinex/docs binding inside that material, not this bootstrap manifest.' }),
+    boundary: 'Portable Tooling bootstrap transport authority only. Transport orientation bootstrap and canonical schema-material authority remain separate concerns.'
+  });
+  const manifestBytes = new TextEncoder().encode(`${JSON.stringify(sortJson(manifest), null, 2)}\n`);
+  const manifestSha256 = sha256Hex(manifestBytes);
+  const persistentVerification = delivery === 'persistent' ? verifyExpectedPersistentBootstrap(input.expected, manifest, manifestSha256) : Object.freeze({ state: 'not-required' });
+  const summary = Object.freeze({ schema: 'tiinex.portable.tooling-bootstrap.summary.v1', delivery, manifestSha256, representationSha256: runtime.representationSha256, runtimeFiles: runtime.entries.length, runtimeBytes: runtime.totalBytes, status: delivery === 'embedded' ? 'embedded-qualified' : 'persistent-identity-verified', persistentVerification });
+  const files = [transportFile('tiinex.bootstrap/manifest.json', manifestBytes, 'tooling-bootstrap-manifest', 'portable-tooling-bootstrap-control')];
+  if (delivery === 'embedded') for (const entry of runtime.entries) files.push(transportFile(`tiinex.bootstrap/runtime/${entry.path}`, entry.data, 'tooling-bootstrap-runtime', 'portable-tooling-bootstrap-runtime'));
+  return Object.freeze({ manifest, summary, files: Object.freeze(files) });
+}
+
+function verifyExpectedPersistentBootstrap(expected, manifest, manifestSha256) {
+  if (!expected || typeof expected !== 'object' || !Object.keys(expected).length) throw new Error('portable.tooling-bootstrap.persistent-verification.required');
+  const candidate = expected.manifest && typeof expected.manifest === 'object' ? expected.manifest : expected;
+  const expectedRepresentationSha256 = String(candidate.runtime?.representationSha256 || candidate.representationSha256 || expected.representationSha256 || '');
+  if (!expectedRepresentationSha256) throw new Error('portable.tooling-bootstrap.persistent-verification.representation-required');
+  if (expectedRepresentationSha256 !== manifest.runtime.representationSha256) throw new Error('portable.tooling-bootstrap.persistent-verification.representation-mismatch');
+  const expectedFiles = Number(candidate.runtime?.files ?? candidate.runtimeFiles ?? expected.runtimeFiles ?? 0);
+  if (expectedFiles && expectedFiles !== manifest.runtime.files) throw new Error('portable.tooling-bootstrap.persistent-verification.file-count-mismatch');
+  const expectedBytes = Number(candidate.runtime?.bytes ?? candidate.runtimeBytes ?? expected.runtimeBytes ?? 0);
+  if (expectedBytes && expectedBytes !== manifest.runtime.bytes) throw new Error('portable.tooling-bootstrap.persistent-verification.byte-count-mismatch');
+  const expectedManifestSha256 = String(expected.manifestSha256 || '');
+  if (expectedManifestSha256 && expected.delivery === 'persistent' && expectedManifestSha256 !== manifestSha256) throw new Error('portable.tooling-bootstrap.persistent-verification.manifest-mismatch');
+  return Object.freeze({ state: 'verified', basis: 'caller-supplied-exact-runtime-identity', representationSha256: manifest.runtime.representationSha256, runtimeFiles: manifest.runtime.files, runtimeBytes: manifest.runtime.bytes, manifestSha256 });
+}
+
+async function enumerateRuntimeDependencyGraph(runtimeRoot, options = {}) {
+  const maxFiles = positiveInteger(options.maxFiles, 4000);
+  const queue = ['tools/tiinex-portable.mjs'];
+  const seen = new Set();
+  const files = new Map();
+  while (queue.length) {
+    const relative = normalizeRelativePath(queue.shift());
+    if (seen.has(relative)) continue;
+    seen.add(relative);
+    if (seen.size > maxFiles) throw new Error(`portable.tooling-bootstrap.file-limit:${maxFiles}`);
+    const absolute = path.resolve(runtimeRoot, relative);
+    assertInside(runtimeRoot, absolute, 'portable.tooling-bootstrap.path.outside-runtime');
+    const info = await lstat(absolute);
+    if (!info.isFile()) throw new Error(`portable.tooling-bootstrap.dependency.not-file:${relative}`);
+    const data = new Uint8Array(await readFile(absolute));
+    files.set(relative, data);
+    if (!/\.(?:m?js|cjs)$/i.test(relative)) continue;
+    const text = new TextDecoder().decode(data);
+    for (const specifier of staticRelativeSpecifiers(text)) {
+      const resolved = resolveImportRelative(relative, specifier);
+      if (resolved) queue.push(resolved);
+    }
+  }
+  for (const explicit of ['package.json', 'src/tooling/portable/bootstrap/tiinex.llm.bootstrap.md', 'src/tooling/portable/bootstrap/tiinex.llm.bootstrap.pointer.json']) if (!files.has(explicit)) files.set(explicit, new Uint8Array(await readFile(path.resolve(runtimeRoot, explicit))));
+  const canonicalRoot = path.resolve(runtimeRoot, 'src/tooling/portable/schema/bootstrap');
+  for (const relative of await enumerateFilesUnder(canonicalRoot, runtimeRoot)) if (!files.has(relative)) files.set(relative, new Uint8Array(await readFile(path.resolve(runtimeRoot, relative))));
+  const entries = [...files.entries()].map(([entryPath, data]) => Object.freeze({ path: entryPath, data, bytes: data.byteLength, sha256: sha256Hex(data) })).sort((a, b) => a.path.localeCompare(b.path));
+  const totalBytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+  const representationSha256 = sha256Text(stableJson(entries.map(({ path: entryPath, bytes, sha256 }) => ({ path: `runtime/${entryPath}`, bytes, sha256 }))));
+  return Object.freeze({ entries: Object.freeze(entries), totalBytes, representationSha256 });
+}
+
+async function enumerateFilesUnder(root, runtimeRoot) {
+  const out = [];
+  const queue = [root];
+  while (queue.length) {
+    const current = queue.shift();
+    const entries = await readdir(current, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) queue.push(absolute);
+      else if (entry.isFile()) out.push(normalizeRelativePath(path.relative(runtimeRoot, absolute)));
+    }
+  }
+  return out.sort();
+}
+function staticRelativeSpecifiers(text = '') { const out = []; IMPORT_RE.lastIndex = 0; let match; while ((match = IMPORT_RE.exec(text))) if (String(match[1] || '').startsWith('.')) out.push(match[1]); return out; }
+function resolveImportRelative(fromFile, specifier) { const clean = String(specifier || '').split('?')[0].split('#')[0]; if (!clean.startsWith('.')) return ''; let resolved = normalizeRelativePath(path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), clean))); if (!path.posix.extname(resolved)) resolved = `${resolved}.js`; return resolved; }
+function transportFile(filePath, data, kind, logicalKind) { return Object.freeze({ path: filePath, data, kind, logicalKind, mediaType: mediaTypeForPath(filePath), boundary: 'Manifest-declared portable Tooling bootstrap transport byte. Co-location does not grant bootstrap authority; exact manifest membership and digest are required.' }); }
+function normalizeDelivery(value) { const delivery = String(value || 'embedded').trim().toLowerCase(); if (!['embedded', 'persistent'].includes(delivery)) throw new Error(`portable.tooling-bootstrap.delivery.unsupported:${delivery}`); return delivery; }
+function mediaTypeForPath(value = '') { const lower = String(value).toLowerCase(); if (lower.endsWith('.md')) return 'text/markdown'; if (lower.endsWith('.json')) return 'application/json'; if (/\.(?:m?js|cjs)$/.test(lower)) return 'text/javascript'; if (lower.endsWith('.ts')) return 'text/typescript'; if (lower.endsWith('.css')) return 'text/css'; if (lower.endsWith('.html')) return 'text/html'; if (/\.(?:yml|yaml)$/.test(lower)) return 'text/yaml'; if (lower.endsWith('.txt')) return 'text/plain'; return 'application/octet-stream'; }
+function normalizeRelativePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').split('/').filter((part) => part && part !== '.').join('/'); }
+function inside(root, absolute) { const relative = path.relative(root, absolute); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)); }
+function assertInside(root, absolute, code) { if (!inside(root, absolute)) throw new Error(code); }
+function positiveInteger(value, fallback) { const parsed = Number.parseInt(value, 10); return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback; }
+function sha256Text(value = '') { return createHash('sha256').update(String(value), 'utf8').digest('hex'); }
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]).filter(([, item]) => typeof item !== 'undefined')); }

package/src/tooling/portable/adapters/node/handoff.manufacture.enumeration.js

@@ -0,0 +1,94 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { sha256Hex } from '../../../../export/package.bytes.js';
+import { safeWorkspaceToken, serializableMetadata } from './handoff.manufacture.multiRoot.js';
+
+export const PORTABLE_NODE_WORKSPACE_ENUMERATION_SCHEMA_ID = 'tiinex.portable.node-workspace-enumeration.v1';
+export const DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_DIRECTORIES = Object.freeze(['.git', '.tiinex', 'node_modules', '.site-publish']);
+const DEFAULT_MAX_FILES = 10000;
+
+export async function enumerateNodeWorkspace(rootInput = '.', options = {}) {
+  const root = path.resolve(String(rootInput || '.'));
+  const maxFiles = positiveInteger(options.maxFiles, DEFAULT_MAX_FILES);
+  const excluded = new Set([...(options.excludeDirectories || DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_DIRECTORIES)].map(String));
+  const queue = [root];
+  const absoluteFiles = [];
+  const skippedSymlinks = [];
+  while (queue.length) {
+    const current = queue.shift();
+    const entries = await readdir(current, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (entry.isDirectory() && excluded.has(entry.name)) continue;
+      const absolute = path.join(current, entry.name);
+      if (entry.isSymbolicLink()) { skippedSymlinks.push(normalizeRelativePath(path.relative(root, absolute))); continue; }
+      if (entry.isDirectory()) queue.push(absolute);
+      else if (entry.isFile()) absoluteFiles.push(absolute);
+      if (absoluteFiles.length > maxFiles) {
+        return Object.freeze({
+          schema: PORTABLE_NODE_WORKSPACE_ENUMERATION_SCHEMA_ID,
+          status: 'file-limit-exceeded',
+          maxFiles,
+          observedFiles: absoluteFiles.length,
+          materialization: null,
+          evidence: Object.freeze({ state: 'blocked', proof: 'deterministic-node-enumeration-v1', maxFiles, observedFiles: absoluteFiles.length })
+        });
+      }
+    }
+  }
+  absoluteFiles.sort((a, b) => normalizeRelativePath(path.relative(root, a)).localeCompare(normalizeRelativePath(path.relative(root, b))));
+  const entries = [];
+  const includedEntries = [];
+  let totalBytes = 0;
+  for (const absolute of absoluteFiles) {
+    const relative = normalizeRelativePath(path.relative(root, absolute));
+    const data = new Uint8Array(await readFile(absolute));
+    const bytes = data.byteLength;
+    const sha256 = sha256Hex(data);
+    totalBytes += bytes;
+    entries.push(Object.freeze({ path: relative, data, bytes, sha256, mediaType: mediaTypeForPath(relative) }));
+    includedEntries.push(Object.freeze({ path: relative, bytes, sha256, referenceTarget: '' }));
+  }
+  const workspaceId = safeWorkspaceToken(options.workspaceId || path.basename(root) || 'workspace');
+  const workspaceTitle = String(options.workspaceTitle || '').trim();
+  const evidencePayload = Object.freeze({
+    schema: 'tiinex.portable.workspace-completeness-evidence.v1',
+    state: 'qualified',
+    proof: 'deterministic-node-enumeration-v1',
+    boundary: 'regular-files-under-workspace-root',
+    workspaceId,
+    entryCount: includedEntries.length,
+    totalBytes,
+    exclusions: Object.freeze({ directories: Object.freeze([...excluded].sort()), symbolicLinks: 'excluded-and-reported' }),
+    skippedSymlinks: Object.freeze(skippedSymlinks.sort()),
+    entriesFingerprint: sha256Text(stableJson(includedEntries))
+  });
+  return Object.freeze({
+    schema: PORTABLE_NODE_WORKSPACE_ENUMERATION_SCHEMA_ID,
+    status: 'qualified-complete',
+    rootBoundary: '.',
+    evidence: evidencePayload,
+    materialization: Object.freeze({
+      id: workspaceId,
+      title: workspaceTitle || workspaceId,
+      state: 'complete',
+      source: Object.freeze({
+        kind: 'node-directory-enumeration',
+        workspaceId,
+        boundary: '.',
+        operatorMetadata: Object.freeze(serializableMetadata(options.sourceMetadata || {})),
+        authority: 'none'
+      }),
+      completenessEvidence: evidencePayload,
+      entries: Object.freeze(entries),
+      includedEntries: Object.freeze(includedEntries)
+    })
+  });
+}
+
+function normalizeRelativePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, ''); }
+function mediaTypeForPath(value = '') { const lower = String(value).toLowerCase(); if (lower.endsWith('.md')) return 'text/markdown'; if (lower.endsWith('.json')) return 'application/json'; if (/\.(?:m?js|cjs)$/.test(lower)) return 'text/javascript'; if (lower.endsWith('.ts')) return 'text/typescript'; if (lower.endsWith('.css')) return 'text/css'; if (lower.endsWith('.html')) return 'text/html'; if (/\.(?:yml|yaml)$/.test(lower)) return 'text/yaml'; if (lower.endsWith('.txt')) return 'text/plain'; return 'application/octet-stream'; }
+function positiveInteger(value, fallback) { const parsed = Number.parseInt(value, 10); return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback; }
+function sha256Text(value) { return sha256Hex(new TextEncoder().encode(String(value))); }
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }