@tiinex/core 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared host-neutral Tiinex implementation core for artifacts, schemas, validation, lineage, grounding, Handoffs, provenance and deterministic workflows.",
   "type": "module",
   "sideEffects": true,
@@ -133,7 +133,9 @@
     "./portable-entry": "./tools/tiinex-portable.mjs",
     "./schema-bootstrap": "./src/tooling/portable/schema/bootstrap/canonical.pack.js",
     "./node/release": "./src/release/run.mjs",
-    "./node/release-policy": "./src/release/policy.mjs"
+    "./node/release-policy": "./src/release/policy.mjs",
+    "./tooling/portable/comparison/sourceFrontierComparison.js": "./src/tooling/portable/comparison/sourceFrontierComparison.js",
+    "./tooling/portable/adapters/node/sourceFrontierComparison.js": "./src/tooling/portable/adapters/node/sourceFrontierComparison.js"
   },
   "files": [
     "src",
@@ -165,12 +167,12 @@
     "type": "git",
     "url": "git+https://github.com/Tiinex/core.git"
   },
-  "gitHead": "24c0ac44dcab14259b3adee85fa83434a462f9dc",
+  "gitHead": "52af987f64464878ba9c497921e21b70215c6971",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "24c0ac44dcab14259b3adee85fa83434a462f9dc",
-    "sourceTree": "cbf5f25e875efac11c017d9914efa673bdfc2edb",
+    "sourceCommit": "52af987f64464878ba9c497921e21b70215c6971",
+    "sourceTree": "1a8f10b3166397e65f47d43472abb70367374d4c",
     "repository": "Tiinex/core",
-    "previousVersion": "0.2.0"
+    "previousVersion": "0.4.0"
   }
 }

package/src/public/index.js

@@ -14,3 +14,24 @@ export {
 } from './companionResources.js';
 
 export { projectSchemaAncestry } from './schemaAncestry.js';
+export {
+  SECURE_TRANSPORT_V1_PROFILE,
+  SECURE_TRANSPORT_V1_ENVELOPE_CONTRACT,
+  qualifySecureTransportV1Envelope,
+  sealPasswordWorkspacePayload,
+  openPasswordWorkspacePayload,
+  replacePasswordWorkspaceRecipients,
+  secureTransportV1AuthenticatedMetadata
+} from '../transport/secureTransportV1.js';
+
+export {
+  PORTABLE_SOURCE_FRONTIER_SCHEMA_ID,
+  PORTABLE_SOURCE_FRONTIER_COMPARISON_SCHEMA_ID,
+  PORTABLE_SOURCE_FRONTIER_SUMMARY_SCHEMA_ID,
+  createPortableSourceFrontier,
+  createPortableWorkspaceSnapshot,
+  comparePortableSourceFrontiers,
+  reconcilePortableSourceFrontiers,
+  compareOrReconcilePortableSourceFrontiers,
+  projectPortableSourceFrontierComparisonSummary
+} from '../tooling/portable/comparison/sourceFrontierComparison.js';

package/src/public/node.js

@@ -1,2 +1,3 @@
 export * from './index.js';
 export * from '../tooling/portable/index.js';
+export * from '../tooling/portable/adapters/node/sourceFrontierComparison.js';

package/src/release/plan.mjs

@@ -16,13 +16,26 @@ export function releasePlan({pkg,metadata,sourceCommit,messages=[],previousPacka
  if(metadata?.versions?.[decision.targetVersion])throw Error('release.version.collision');
  return {policy:RELEASE_POLICY,action:'publish',name:pkg.name,version:decision.targetVersion,previousVersion:last?.version||null,previousCommit:last?.tiinexRelease?.sourceCommit||last?.gitHead||null,sourceCommit,decision};
 }
+export function publishedArchiveState(metadata,{version,integrity}) {
+ const published=metadata?.versions?.[version];
+ if(!published)return {status:'absent',published:null};
+ if(published.dist?.integrity!==integrity)return {status:'collision',published};
+ return {status:'exact',published};
+}
 export function assertPublishContext(env,repository) {
  if(env.GITHUB_ACTIONS!=='true'||!['push','workflow_dispatch'].includes(env.GITHUB_EVENT_NAME)||env.GITHUB_REF!=='refs/heads/master'||env.GITHUB_REPOSITORY!==repository)throw Error('release.master-only: publishing requires this repository on refs/heads/master');
  if(env.TIINEX_ENABLE_NPM_PUBLISH!=='true')throw Error('release.not-enabled');
 }
-export async function readRegistry(name,{fetcher=globalThis.fetch}={}) {
- const response=await fetcher(`https://registry.npmjs.org/${encodeURIComponent(name)}`,{headers:{Accept:'application/json'},signal:AbortSignal.timeout(30000)});
- if(response.status===404)return {name,versions:{}};
- if(!response.ok)throw Error(`release.registry.failure:${response.status}`);
- const data=await response.json();if(data.name!==name||!data.versions||typeof data.versions!=='object')throw Error('release.registry.invalid-response');return data;
+export async function readRegistry(name,{fetcher=globalThis.fetch,attempts=1,retryDelayMs=250,sleeper=(ms)=>new Promise(resolve=>setTimeout(resolve,ms))}={}) {
+ const count=Math.max(1,Number.isInteger(attempts)?attempts:1);
+ for(let attempt=1;attempt<=count;attempt+=1){
+  const response=await fetcher(`https://registry.npmjs.org/${encodeURIComponent(name)}`,{headers:{Accept:'application/json','Cache-Control':'no-cache'},signal:AbortSignal.timeout(30000)});
+  if(response.status===404){
+   if(attempt<count){await sleeper(Math.max(0,retryDelayMs)*attempt);continue;}
+   return {name,versions:{}};
+  }
+  if(!response.ok)throw Error(`release.registry.failure:${response.status}`);
+  const data=await response.json();if(data.name!==name||!data.versions||typeof data.versions!=='object')throw Error('release.registry.invalid-response');return data;
+ }
+ return {name,versions:{}};
 }

package/src/release/run.mjs

@@ -2,7 +2,7 @@ import {readFile,writeFile,mkdir,rm,cp,realpath,stat} from 'node:fs/promises';
 import {spawnSync} from 'node:child_process';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
-import {assertPublishContext,readRegistry,releasePlan,compareVersion} from './plan.mjs';
+import {assertPublishContext,readRegistry,releasePlan,compareVersion,publishedArchiveState} from './plan.mjs';
 import {parseSemver} from './policy.mjs';
 const npm=process.platform==='win32'?'npm.cmd':'npm';
 function run(command,args,cwd,{allowFailure=false}={}) {const r=spawnSync(command,args,{cwd,encoding:'utf8',timeout:180000,maxBuffer:32*1024*1024,shell:process.platform==='win32'&&command===npm});if(r.error||(!allowFailure&&r.status!==0))throw Error(`${command} ${args[0]} failed: ${r.error?.message||r.stderr||r.stdout}`);return r;}
@@ -16,6 +16,7 @@ export async function runRelease({cwd=process.cwd(),argv=process.argv.slice(2),e
  const pkg=JSON.parse(await readFile(path.join(cwd,'package.json'),'utf8'));
  const policy=JSON.parse(await readFile(path.join(cwd,'.github/release-policy.json'),'utf8'));
  const repository=policy.repository;
+ const registryReadOptions=command==='bootstrap'?{}:env.GITHUB_ACTIONS==='true'?{attempts:6,retryDelayMs:500}:{};
  if(pkg.repository?.url!==`git+https://github.com/${repository}.git`||!repository.startsWith('Tiinex/'))throw Error('release.repository.mismatch');
  const git=(args,opts)=>run('git',args,cwd,opts);
  const head=git(['rev-parse','HEAD']).stdout.trim();
@@ -26,18 +27,19 @@ export async function runRelease({cwd=process.cwd(),argv=process.argv.slice(2),e
   if(p.action==='skip'){console.log(JSON.stringify(p));return p;}
   const file=path.resolve(cwd,p.file);if(path.dirname(file)!==path.join(cwd,'.release'))throw Error('release.archive-path');
   const bytes=await readFile(file);if(createHash('sha512').update(bytes).digest('base64')!==p.integrity.slice(7))throw Error('release.archive-tampered');
-  const meta=await readRegistry(pkg.name);const existing=meta.versions[p.version];
-  if(existing){if(existing.dist?.integrity!==p.integrity)throw Error('release.version.collision');console.log('Already published exact archive');return p;}
+  const meta=await readRegistry(pkg.name,{...registryReadOptions,attempts:8});const existingState=publishedArchiveState(meta,{version:p.version,integrity:p.integrity});
+  if(existingState.status==='collision')throw Error('release.version.collision');
+  if(existingState.status==='exact'){console.log('Already published exact archive');return p;}
   const latest=Object.values(meta.versions).filter(v=>!parseSemver(v.version).prerelease).sort((a,b)=>compareVersion(a.version,b.version)).at(-1);
   if(latest&&compareVersion(latest.version,p.version)>=0)throw Error('release.newer-version-already-published');
   const result=run(npm,['publish',file,'--ignore-scripts','--access','public','--tag','latest','--provenance'],cwd,{allowFailure:true});
-  if(result.status!==0){const check=await readRegistry(pkg.name);if(check.versions[p.version]?.dist?.integrity!==p.integrity)throw Error('release.publish.failed: '+result.stderr);}
+  if(result.status!==0){const check=await readRegistry(pkg.name,{...registryReadOptions,attempts:10,retryDelayMs:750});const failedState=publishedArchiveState(check,{version:p.version,integrity:p.integrity});if(failedState.status==='collision')throw Error('release.version.collision-after-publish');if(failedState.status!=='exact')throw Error('release.publish.failed: '+result.stderr);}
   console.log(JSON.stringify({...p,published:true}));return p;
  }
  if(command==='prepare') {assertPublishContext(env,repository);if(env.GITHUB_SHA!==head)throw Error('release.checkout-is-not-event-commit');}
  if(command==='bootstrap' && git(['branch','--show-current']).stdout.trim()!=='master')throw Error('release.bootstrap.master-only');
  if(git(['status','--porcelain','--untracked-files=no']).stdout.trim())throw Error('release.dirty-source');
- const metadata=await readRegistry(pkg.name);
+ const metadata=await readRegistry(pkg.name,registryReadOptions);
  if(command==='bootstrap'&&Object.keys(metadata.versions).length)throw Error('Package exists: configure OIDC and use the master workflow, not bootstrap.');
  if(command==='bootstrap') { const check=pkg.scripts?.validate?'validate':pkg.scripts?.check?'check':'test'; run(npm,['run',check],cwd); }
  const previous=Object.values(metadata.versions).filter(v=>!parseSemver(v.version).prerelease).sort((a,b)=>compareVersion(a.version,b.version)).at(-1);

package/src/tooling/portable/adapters/cli/cli.command-input.js

@@ -10,6 +10,7 @@ import { prepareQualifyColdStartCommandInput } from './cli.cold-start-input.js';
 import { reductionPreflightCliInput } from './cli.reduction-input.js';
 import {land} from './cli.land.js';
 import { OPERATIONS_WITHOUT_EXPLICIT_MATERIAL } from './cli.material-policy.js';
+import { prepareSourceFrontierComparisonCliInput } from './cli.source-frontier-comparison.js';
 
 export async function commandInput(parsed, runtime = {}) {
   const flags = parsed.flags;
@@ -138,6 +139,8 @@ export async function commandInput(parsed, runtime = {}) {
     return { input: { plan: plan.result || plan, receipt: receipt.result || receipt, priorAcceptance: prior.result || prior }, options: {} };
   }
 
+  if (parsed.command === 'compare-source-frontiers') return prepareSourceFrontierComparisonCliInput(parsed, flags);
+
   if (parsed.command === 'manufacture-handoff-package') {
     return prepareHandoffManufactureCliCommand(parsed, runtime);
   }

package/src/tooling/portable/adapters/cli/cli.common-output.js

@@ -1,3 +1,5 @@
+import { projectPortableSourceFrontierComparisonSummary } from '../../comparison/sourceFrontierComparison.js';
+
 const COMMON_DEFAULT_PROJECTION = 'common-default';
 
 export function projectCommonCliDefaultOutput(result = {}, parsed = {}) {
@@ -5,9 +7,30 @@ export function projectCommonCliDefaultOutput(result = {}, parsed = {}) {
   if (parsed?.command === 'orient-handoff-package') return projectOrientDefault(result, parsed);
   if (parsed?.command === 'project-grounding-readiness') return projectGroundDefault(result, parsed);
   if (parsed?.command === 'manufacture-handoff-package' && parsed?.surfaceCommand === 'handoff') return projectHandoffDefault(result, parsed);
+  if (parsed?.command === 'compare-source-frontiers') return projectCompareDefault(result, parsed);
   return result;
 }
 
+function projectCompareDefault(result = {}, parsed = {}) {
+  const summary = projectPortableSourceFrontierComparisonSummary({ ...result, schema: result.resultSchema || result.schema || '' }, { maxPaths: parsed?.flags?.['max-paths'] || 20 });
+  return Object.freeze({
+    schema: result.schema,
+    operation: result.operation || 'compare-source-frontiers',
+    resultSchema: result.resultSchema,
+    projection: COMMON_DEFAULT_PROJECTION,
+    status: summary.status,
+    state: summary.state,
+    mode: summary.mode,
+    inputs: summary.inputs,
+    workspaces: summary.workspaces,
+    counts: summary.counts,
+    findingSummary: summary.findingSummary,
+    actionableFindings: summary.actionableFindings,
+    detail: Object.freeze({ fullReceipt: Object.freeze({ command: String(parsed.surfaceCommand || 'compare'), flag: '--full' }) }),
+    boundary: summary.boundary
+  });
+}
+
 function projectOrientDefault(result = {}, parsed = {}) {
   const projection = result?.entrypoint?.projection || {};
   const routes = (result.routes || projection.routes || []).map(projectOrientRoute);

package/src/tooling/portable/adapters/cli/cli.handoff-manufacture.js

@@ -28,6 +28,7 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
   if (!flags.route && handoffPath) flags.route = handoffPath;
   if (!flags.output && !flags['output-dir'] && parsed.surfaceCommand === 'handoff' && continuationState.returnOutputDir) flags['output-dir'] = continuationState.returnOutputDir;
   const materialBindings = await readOptionalJson(flags['material-bindings'] || flags.materials);
+  const packageParentWorkspaceIds = splitFlag(flags['package-parent-workspaces']);
   const packageParentWorkspaceAliases = await readOptionalJson(flags['package-parent-workspace-aliases']);
   const operatorCarrierProfile = await readOptionalJson(flags['carrier-profile']);
   const expectedToolingBootstrap = await readOptionalJson(flags['tooling-bootstrap-manifest']);
@@ -126,6 +127,7 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
     packageParentBundle,
     packageParentPath: parentPackagePath ? path.resolve(parentPackagePath) : '',
     packageParentSha256,
+    packageParentWorkspaceIds,
     packageParentWorkspaceAliases
   }, runtime);
   return {
@@ -193,7 +195,7 @@ function projectWorkspaceCarrierHumanOutput(result = {}) {
   const projection = result.carrierProjection || {};
   const ready = result.status === 'ready' && projection.status === 'ready' && projection.mode === 'workspace' && (projection.routes || []).length === 0;
   const dimension = String(projection.lineage?.dimension || '001');
-  const filename = `tiinex-workspace-${dimension}.handoff-package.zip`;
+  const filename = `tiinex-${dimension}.handoff-package.zip`;
   return Object.freeze({
     schema: 'tiinex.portable.handoff-human-output.v1',
     status: ready ? 'ready' : 'blocked',

package/src/tooling/portable/adapters/cli/cli.help.js

@@ -12,6 +12,7 @@ export function portableCliHelpText(commandPrefix = '', surfaceCommand = '') {
     `${command} ground <handoff-package.zip> --route <Continue-from> --holder-role <recipient-role> --continue <workspace-dir>`,
     `${command} author <workspace-dir> --schema <schema-id> (--path <workspace-relative-artifact> | --directory <workspace-relative-directory>) --body <body.md> [--parent <workspace-relative-or-qualified-parent>] [--parent-source <local-parent-file>] [--title <title>] [--summary <summary>] [--why <why>]`,
     `${command} handoff <workspace-dir>`,
+    `${command} compare --left-kind <kind> --left <path> --right-kind <kind> --right <path> [side selectors]`,
     '',
     `Handoff aliases: ${command} orient <carrier.zip>; ${command} validate <carrier.zip>`,
     `Advanced/internal catalog: ${command} operations`,
@@ -20,7 +21,7 @@ export function portableCliHelpText(commandPrefix = '', surfaceCommand = '') {
     '- `orient`, `ground`, and public `handoff` use compact decision-first default projections; add `--full` on the same command for the complete qualified receipt.',
     '- `ground` is read-only; append `--continue <workspace-dir>` only after `grounded-to-act` to materialize the selected carried Workspace and runtime-only `.tiinex/continuation.json`.',
     '- `author` uses continuation state to infer ordinary Parent continuity, seal c14n-v2 integrity, audit, and stage; invalid artifacts are not retained.',
-    '- `handoff` uses continuation state plus the latest qualified authored Handoff to manufacture the canonical return carrier and excludes runtime-only `.tiinex` state. When a package parent carries an older Workspace id that has been explicitly renamed, advanced manufacture may bind that predecessor id to a supplied current Workspace with `--package-parent-workspace-aliases`; aliases never infer source identity. Normal operator completion is one Handoff package plus the exact routing text; markdown-capable hosts render that routing in a fenced code block, and do not emit loose Evidence/Handoff markdown as extra transport payloads.',
+    '- `handoff` uses continuation state plus the latest qualified authored Handoff to manufacture the canonical return carrier and excludes runtime-only `.tiinex` state. A received `--package-parent` continues carrier lineage only; it never selects parent Workspace source by itself. Advanced manufacture may opt into exact parent snapshots with `--package-parent-workspaces <id,...|all>` and may bind an explicitly selected renamed predecessor with `--package-parent-workspace-aliases`; aliases never infer source identity. Normal operator completion is one Handoff package plus the exact routing text; markdown-capable hosts render that routing in a fenced code block, and do not emit loose Evidence/Handoff markdown as extra transport payloads.',
     '- Remote reads/writes remain explicit host concerns. Tooling operation safety does not create or revoke semantic Task/Handoff authority.',
     '',
     'Use `<common-command> --help` for focused common-path usage. Use `operations` deliberately for the advanced/internal operation catalog.'
@@ -28,6 +29,21 @@ export function portableCliHelpText(commandPrefix = '', surfaceCommand = '') {
 }
 
 function commonCommandHelp(command, surfaceCommand) {
+  if (surfaceCommand === 'compare' || surfaceCommand === 'compare-source-frontiers') return [
+    'Tiinex portable tooling — compare source frontiers',
+    '',
+    'Two-way:',
+    `${command} compare --left-kind <local-workspace|local-frontier|handoff-package> --left <path> --right-kind <kind> --right <path> [--left-id <workspace-id>] [--right-id <workspace-id>] [--left-select <id,...>] [--right-select <id,...>]`,
+    'For local-frontier inputs use `--left-roots <id=path,...>` / `--right-roots <id=path,...>` instead of the side path.',
+    '',
+    'Three-way child-return reconciliation:',
+    `${command} compare --base-kind <kind> --base <path> --incoming-kind <kind> --incoming <path> --current-kind <kind> --current <path> [side ids/selectors/roots]`,
+    '',
+    'Input kind is mandatory and is never guessed from a path. Local source uses the exact deterministic Workspace enumeration contract shared with Handoff manufacture. Handoff packages are qualified by this current Tooling runtime; package bootstrap code is not executed. Password-sealed Workspaces remain `locked` unless a caller uses the public Node API with an already-authorized opened Workspace provider.',
+    'Default output is a compact path-bounded human/LLM projection; add `--full` for the complete machine receipt. Comparison is read-only source-byte evidence only: no merge, semantic diff, staging, commit, push, remote acquisition, authority, or acceptance inference.',
+    '',
+    `Advanced/internal catalog: ${command} operations`
+  ];
   if (surfaceCommand === 'ground') return [
     'Tiinex portable tooling — ground',
     '',
@@ -54,7 +70,7 @@ function commonCommandHelp(command, surfaceCommand) {
     '',
     `${command} handoff <workspace-dir>`,
     '',
-    'Infers the latest qualified authored Handoff, selected Workspace identity/target, received package parent, unchanged sibling Workspace providers, canonical projected filename, and return output directory. The default receipt keeps output identity, routing text, closure/workspace qualification, verification, and actionable findings compact; add `--full` for the complete manufacture receipt. Normal operator completion is exactly one Handoff package plus the adjacent exact routing text. In markdown-capable hosts render that routing in a fenced code block; do not emit canonical Workspace Evidence/Handoff markdown as additional loose transport files. Runtime-only `.tiinex` state is excluded from canonical manufacture.',
+    'Infers the latest qualified authored Handoff, selected Workspace identity/target, received package parent as carrier-lineage evidence, canonical projected filename, and return output directory. It does not implicitly carry sibling Workspaces from the received package; advanced manufacture must select exact reusable parent snapshots with `--package-parent-workspaces <id,...|all>`. The default receipt keeps output identity, routing text, closure/workspace qualification, verification, and actionable findings compact; add `--full` for the complete manufacture receipt. Normal operator completion is exactly one Handoff package plus the adjacent exact routing text. In markdown-capable hosts render that routing in a fenced code block; do not emit canonical Workspace Evidence/Handoff markdown as additional loose transport files. Runtime-only `.tiinex` state is excluded from canonical manufacture.',
     '',
     `Advanced/internal catalog: ${command} operations`
   ];

package/src/tooling/portable/adapters/cli/cli.material-policy.js

@@ -2,6 +2,5 @@ export const OPERATIONS_WITHOUT_EXPLICIT_MATERIAL = new Set([
   'prepare-task','prepare-materialization','create-local-artifact-set','create-local-draft','plan-host-action','accept-host-receipt',
   'describe-checkpoint-gate','qualify-checkpoint','describe-schema-chain','schema-guide','plan-artifact','list-material-providers',
   'resolve-schema-material','resolve-schema-chain-material','materialize-durable-findings','build-runtime-package','roundtrip-runtime-package',
-  'compare-source-frontiers',
   'describe-cold-start-ingress','project-cold-start-host','qualify-cold-start','ground-cold-consumer'
 ]);

package/src/tooling/portable/adapters/cli/cli.operator-bridge.js

@@ -3,19 +3,6 @@ export async function prepareOperatorBridgeCliInput(command = '', material = {},
     const repositories = await readOptionalJson(flags.repositories);
     return { input: { ...material, repositories: repositories.repositories || repositories }, options: {} };
   }
-  if (command === 'compare-source-frontiers') {
-    return {
-      input: {
-        leftKind: flags['left-kind'] || flags.leftKind || '',
-        left: flags.left || '',
-        leftId: flags['left-id'] || flags.leftId || '',
-        rightKind: flags['right-kind'] || flags.rightKind || '',
-        right: flags.right || '',
-        rightSelect: flags['right-select'] || flags.rightSelect || ''
-      },
-      options: {}
-    };
-  }
   if (command === 'project-handoff-authoring-plan') return { input: { ...material, parentPath: flags.parent || flags['parent-path'] || '', title: flags.title || '' }, options: {} };
   if (command === 'project-handoff-endpoints') return { input: { ...material, workspaceId: flags['workspace-id'] || flags.workspace || 'workspace' }, options: {} };
   if (command === 'project-operator-context') {

package/src/tooling/portable/adapters/cli/cli.run.js

@@ -425,7 +425,7 @@ function withCliPhaseTiming(result = {}, timing = {}) {
 function parseArgs(argv=[]) {
   const args=[...argv],first=args.shift()||'';
   if(first==='--help'||first==='-h') return {command:'help',flags:{help:true},positionals:[]};
-  const command=({orient:'orient-handoff-package',ground:'project-grounding-readiness',receive:'qualify-cold-start',validate:'audit-handoff-package-context',handoff:'manufacture-handoff-package',author:'author'})[first]||first;
+  const command=({orient:'orient-handoff-package',ground:'project-grounding-readiness',receive:'qualify-cold-start',validate:'audit-handoff-package-context',handoff:'manufacture-handoff-package',author:'author',compare:'compare-source-frontiers'})[first]||first;
   const flags={},positionals=[];
   while(args.length){const token=args.shift();if(!token.startsWith('--')){positionals.push(token);continue;}const key=token.slice(2);flags[key]=!args.length||args[0].startsWith('--')?true:args.shift();}
   return {command,flags,positionals,surfaceCommand:first};

package/src/tooling/portable/adapters/cli/cli.source-frontier-comparison.js

@@ -0,0 +1,50 @@
+import { prepareNodeSourceFrontierComparisonInput } from '../node/sourceFrontierComparison.js';
+
+export async function prepareSourceFrontierComparisonCliInput(parsed = {}, flags = {}) {
+  const threeWay = hasAny(flags, ['base', 'base-kind', 'incoming', 'incoming-kind', 'current', 'current-kind']);
+  const descriptorOptions = {
+    maxFiles: flags['max-files'],
+    maxCarrierFiles: flags['max-carrier-files'],
+    maxTextBytes: flags['max-text-bytes']
+  };
+  if (threeWay) {
+    const request = {
+      base: descriptorFromFlags('base', flags),
+      incoming: descriptorFromFlags('incoming', flags),
+      current: descriptorFromFlags('current', flags)
+    };
+    return { input: await prepareNodeSourceFrontierComparisonInput(request, descriptorOptions), options: {} };
+  }
+  const request = {
+    left: descriptorFromFlags('left', flags),
+    right: descriptorFromFlags('right', flags)
+  };
+  return { input: await prepareNodeSourceFrontierComparisonInput(request, descriptorOptions), options: {} };
+}
+
+function descriptorFromFlags(prefix, flags) {
+  const kind = String(flags[`${prefix}-kind`] || '').trim();
+  const root = String(flags[prefix] || '').trim();
+  const workspaceId = String(flags[`${prefix}-id`] || flags[`${prefix}-workspace-id`] || '').trim();
+  const select = splitFlag(flags[`${prefix}-select`]);
+  const roots = parseRootBindings(flags[`${prefix}-roots`]);
+  return Object.freeze({
+    kind,
+    ...(root ? { path: root } : {}),
+    ...(workspaceId ? { workspaceId } : {}),
+    ...(select.length ? { workspaceIds: select } : {}),
+    ...(roots.length ? { workspaces: roots } : {}),
+    ...(flags[`${prefix}-label`] ? { label: String(flags[`${prefix}-label`]) } : {})
+  });
+}
+
+function parseRootBindings(value) {
+  const items = splitFlag(value);
+  return items.map((item) => {
+    const eq = item.indexOf('=');
+    if (eq <= 0 || eq === item.length - 1) return Object.freeze({ workspaceId: '', root: item });
+    return Object.freeze({ workspaceId: item.slice(0, eq).trim(), root: item.slice(eq + 1).trim() });
+  });
+}
+function splitFlag(value) { return !value || value === true ? [] : String(value).split(',').map((item) => item.trim()).filter(Boolean); }
+function hasAny(flags, keys) { return keys.some((key) => Object.prototype.hasOwnProperty.call(flags, key)); }

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

@@ -15,6 +15,7 @@ import {
 } from './handoff.manufacture.requirements.js';
 import {
   expandBoundedParentBoundaryClosure,
+  expandRouteParentBoundaryClosure,
   normalizeWorkspaceScopes,
   normalizeWorkspaceTargetBindings,
   projectBoundedWorkspaceMaterialization
@@ -68,6 +69,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     currentWorkspaceIds: [...seenWorkspaceIds],
     parentPackagePath: input.packageParentPath || '',
     parentPackageSha256: input.packageParentSha256 || '',
+    workspaceIds: input.packageParentWorkspaceIds || input.reusePackageParentWorkspaceIds || [],
     workspaceAliases: input.packageParentWorkspaceAliases || input.workspaceAliases || {}
   });
   const additionalEnumerationsPromise = Promise.all(additionalWorkspaceInputs.map(async ({ descriptor, id, root, requestedTitle }) => {
@@ -114,6 +116,11 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     workspaceEnumerations.push(Object.freeze({ id, root: '', evidence: inheritedEnumeration.evidence, provider: 'qualified-package-parent-workspace' }));
     workspaceRuntimeById.set(id, Object.freeze({ id, root: '', enumeration: inheritedEnumeration, provider: 'qualified-package-parent-workspace' }));
   }
+  for (const provided of packageParentReuse.providers || []) {
+    const id = safeWorkspaceToken(provided.id || provided.enumeration?.materialization?.id || '');
+    if (!id || workspaceRuntimeById.has(id)) continue;
+    workspaceRuntimeById.set(id, Object.freeze({ id, root: '', enumeration: provided.enumeration, provider: 'qualified-package-parent-workspace-material-provider' }));
+  }
   const transportRoutes = Object.freeze([...(input.transportRoutes || input.handoffRoutes || [])].map((route) => normalizeTransportRoute(route, workspaceId)).filter(Boolean));
   const workspaceTargets = mergeWorkspaceTargetBindings(normalizeWorkspaceTargetBindings({
     primaryWorkspaceId: workspaceId,
@@ -137,6 +144,9 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
   const dependencyClosure = await expandPointerDependencyClosure({ requirements, materials, workspaceRuntimeById, bindings: input.materialBindings || {} });
   requirements = dependencyClosure.requirements;
   materials = dependencyClosure.materials;
+  const routeParentBoundaryClosure = expandRouteParentBoundaryClosure({ requirements, materials, workspaceMaterializations, workspaceRuntimeById, routeSpecs });
+  requirements = routeParentBoundaryClosure.requirements;
+  materials = routeParentBoundaryClosure.materials;
   const parentBoundaryClosure = expandBoundedParentBoundaryClosure({ requirements, materials, workspaceMaterializations, workspaceRuntimeById });
   requirements = parentBoundaryClosure.requirements;
   materials = parentBoundaryClosure.materials;
@@ -167,7 +177,11 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
       toolingBootstrap: toolingBootstrap.summary,
       packageParentWorkspaceReuse: Object.freeze({
         state: String(packageParentReuse.state || ''),
+        providerState: String(packageParentReuse.providerState || ''),
         inspectionStatus: String(packageParentReuse.inspectionStatus || ''),
+        selectionMode: String(packageParentReuse.selectionMode || ''),
+        requestedWorkspaceIds: Object.freeze([...(packageParentReuse.requestedWorkspaceIds || [])].map(String)),
+        providerWorkspaceIds: Object.freeze([...(packageParentReuse.providerWorkspaceIds || [])].map(String)),
         inheritedWorkspaceIds: Object.freeze((packageParentReuse.inherited || []).map((item) => String(item.id || ''))),
         workspaceAliases: Object.freeze([...(packageParentReuse.workspaceAliases || [])].map((item) => Object.freeze({ ...item }))),
         boundary: String(packageParentReuse.boundary || '')

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

@@ -4,48 +4,95 @@ import { parseHandoffPackageV1, RECIPIENT_V2_PACKAGE_V1_ROOT_PATH } from '../../
 
 export function preparePackageParentWorkspaceReuse(input = {}) {
   const bundle = input.bundle || null;
-  if (!bundle?.files?.length) return emptyReuse('unavailable');
   const currentIds = new Set([...(input.currentWorkspaceIds || [])].map(normalizeId).filter(Boolean));
   const workspaceAliases = normalizePackageParentWorkspaceAliases(input.workspaceAliases || input.packageParentWorkspaceAliases || {});
   for (const alias of workspaceAliases.values()) if (!currentIds.has(alias)) throw new Error(`portable.handoff-manufacture.package-parent.workspace-alias.target-unresolved:${alias}`);
+  const selection = normalizePackageParentWorkspaceSelection(input.workspaceIds || input.packageParentWorkspaceIds || input.reuseWorkspaceIds || []);
+  if (!bundle?.files?.length) return emptyReuse('unavailable', { selection, workspaceAliases });
   const inspection = inspectRecipientFacingV2Topology(bundle);
   const declared = declaredPackageWorkspaceBindings(bundle, inspection);
-  if (!declared.length) return emptyReuse('unsupported-parent-surface');
-  if (inspection.status !== 'valid') throw new Error('portable.handoff-manufacture.package-parent.workspace-provider.invalid');
-  const missing = declared.filter((item) => !packageParentWorkspaceSupersededByCurrent(item.workspaceId, currentIds, workspaceAliases));
-  if (!missing.length) return emptyReuse('not-needed');
+  if (!declared.length) {
+    if (selection.mode !== 'none') throw new Error('portable.handoff-manufacture.package-parent.workspace-selection.parent-surface-unresolved');
+    return emptyReuse('not-requested', { selection, workspaceAliases, inspectionStatus: inspection.status, providerState: 'unsupported-parent-surface' });
+  }
+  if (inspection.status !== 'valid') {
+    if (selection.mode !== 'none') throw new Error('portable.handoff-manufacture.package-parent.workspace-provider.invalid');
+    return emptyReuse('not-requested', { selection, workspaceAliases, inspectionStatus: inspection.status, providerState: 'invalid' });
+  }
+  const selected = selectDeclaredPackageParentWorkspaceBindings(declared, selection);
+  const missing = selected.filter((item) => !packageParentWorkspaceSupersededByCurrent(item.workspaceId, currentIds, workspaceAliases));
 
   const providerById = new Map((inspection.workspaceByteProvider?.workspaces || []).map((item) => [normalizeId(item.id), item]));
   const inspectedById = new Map((inspection.workspaces || []).map((item) => [normalizeId(item.workspaceId), item]));
-  const inherited = [];
-  const workspaceTargets = [];
-  for (const binding of missing) {
+  const providers = [];
+  const providerTargetById = new Map();
+  for (const binding of declared) {
     const id = normalizeId(binding.workspaceId);
+    if (packageParentWorkspaceSupersededByCurrent(id, currentIds, workspaceAliases)) continue;
     const provider = providerById.get(id);
     const inspected = inspectedById.get(id);
     if (!provider || provider.state !== 'qualified' || provider.mode !== 'archive' || provider.materialization?.materialization !== 'complete' || inspected?.coverage !== 'complete') {
-      throw new Error(`portable.handoff-manufacture.package-parent.workspace-provider.unqualified:${id}`);
+      if (selection.mode === 'all' || selection.ids.includes(id)) throw new Error(`portable.handoff-manufacture.package-parent.workspace-provider.unqualified:${id}`);
+      continue;
     }
     const targetPath = String(inspected.sourceWorkspaceTargetInnerPath || binding.workspaceArtifactInnerPath || '').trim();
-    if (!targetPath) throw new Error(`portable.handoff-manufacture.package-parent.workspace-target.unresolved:${id}`);
-    inherited.push(buildInheritedEnumeration(provider, {
+    if (!targetPath) {
+      if (selection.mode === 'all' || selection.ids.includes(id)) throw new Error(`portable.handoff-manufacture.package-parent.workspace-target.unresolved:${id}`);
+      continue;
+    }
+    providers.push(buildInheritedEnumeration(provider, {
       parentPackagePath: input.parentPackagePath || '',
       parentPackageSha256: input.parentPackageSha256 || '',
       archivePackagePath: inspected.workspaceArchivePath || binding.snapshotPath || ''
     }));
-    workspaceTargets.push(Object.freeze({ workspaceId: id, path: targetPath, source: 'qualified-package-parent-workspace' }));
+    providerTargetById.set(id, targetPath);
   }
+  const providerEnumerationById = new Map(providers.map((item) => [normalizeId(item.id), item]));
+  const inherited = [];
+  const workspaceTargets = [];
+  for (const binding of missing) {
+    const id = normalizeId(binding.workspaceId);
+    const inheritedProvider = providerEnumerationById.get(id);
+    if (!inheritedProvider) throw new Error(`portable.handoff-manufacture.package-parent.workspace-provider.unqualified:${id}`);
+    inherited.push(inheritedProvider);
+    workspaceTargets.push(Object.freeze({ workspaceId: id, path: providerTargetById.get(id), source: 'qualified-package-parent-workspace' }));
+  }
+  const state = selection.mode === 'none' ? 'not-requested' : (missing.length ? 'qualified' : 'not-needed');
   return Object.freeze({
-    state: 'qualified',
+    state,
+    providers: Object.freeze(providers),
+    providerState: 'qualified',
+    providerWorkspaceIds: Object.freeze(providers.map((item) => normalizeId(item.id))),
     inherited: Object.freeze(inherited),
     workspaceTargets: Object.freeze(workspaceTargets),
     inspectionStatus: inspection.status,
     missingWorkspaceIds: Object.freeze(missing.map((item) => normalizeId(item.workspaceId))),
+    selectionMode: selection.mode,
+    requestedWorkspaceIds: selection.ids,
     workspaceAliases: Object.freeze([...workspaceAliases.entries()].map(([parentWorkspaceId, currentWorkspaceId]) => Object.freeze({ parentWorkspaceId, currentWorkspaceId }))),
-    boundary: 'Exact complete Workspace bytes reused from one independently qualified received package parent. Explicit current Workspace roots take precedence by id, and explicit qualified workspace aliases may supersede a renamed parent-carrier Workspace without carrying stale duplicate source. Parent-carrier placement and lineage remain non-semantic.'
+    boundary: 'Qualified package-parent Workspace snapshots may serve as read-only exact material providers, but complete Workspace carriage is reused only for explicitly selected package-parent Workspace ids. Package-parent carrier lineage alone never selects Workspace source. Explicit current Workspace roots take precedence by id, and explicit qualified workspace aliases may supersede a renamed parent-carrier Workspace without carrying stale duplicate source. Parent-carrier placement and lineage remain non-semantic.'
   });
 }
 
+export function normalizePackageParentWorkspaceSelection(value = []) {
+  const raw = Array.isArray(value) ? value : [value];
+  const tokens = raw.flatMap((item) => String(item || '').split(',')).map((item) => String(item || '').trim()).filter(Boolean);
+  if (!tokens.length) return Object.freeze({ mode: 'none', ids: Object.freeze([]) });
+  if (tokens.some((item) => ['*', 'all'].includes(item.toLowerCase()))) return Object.freeze({ mode: 'all', ids: Object.freeze([]) });
+  return Object.freeze({ mode: 'explicit', ids: Object.freeze([...new Set(tokens.map(normalizeId).filter(Boolean))].sort()) });
+}
+
+export function selectDeclaredPackageParentWorkspaceBindings(declared = [], selection = normalizePackageParentWorkspaceSelection()) {
+  const normalized = [...(declared || [])]
+    .map((item) => Object.freeze({ ...item, workspaceId: normalizeId(item.workspaceId) }))
+    .filter((item) => item.workspaceId);
+  if (selection.mode === 'none') return Object.freeze([]);
+  if (selection.mode === 'all') return Object.freeze(normalized);
+  const byId = new Map(normalized.map((item) => [item.workspaceId, item]));
+  for (const id of selection.ids || []) if (!byId.has(id)) throw new Error(`portable.handoff-manufacture.package-parent.workspace-selection.unresolved:${id}`);
+  return Object.freeze((selection.ids || []).map((id) => byId.get(id)));
+}
+
 function declaredPackageWorkspaceBindings(bundle = {}, inspection = null) {
   const roots = (bundle.files || []).filter((file) => String(file.path || '') === RECIPIENT_V2_PACKAGE_V1_ROOT_PATH);
   if (roots.length === 1) {
@@ -150,8 +197,25 @@ export function packageParentWorkspaceSupersededByCurrent(parentWorkspaceId = ''
   return Boolean(replacement && currentWorkspaceIds.has(replacement));
 }
 
-function emptyReuse(state) {
-  return Object.freeze({ state, inherited: Object.freeze([]), workspaceTargets: Object.freeze([]), inspectionStatus: '', missingWorkspaceIds: Object.freeze([]), workspaceAliases: Object.freeze([]), boundary: 'No package-parent Workspace provider reuse was required.' });
+function emptyReuse(state, options = {}) {
+  const selection = options.selection || normalizePackageParentWorkspaceSelection();
+  const workspaceAliases = options.workspaceAliases || new Map();
+  return Object.freeze({
+    state,
+    providers: Object.freeze([]),
+    providerState: String(options.providerState || 'unavailable'),
+    providerWorkspaceIds: Object.freeze([]),
+    inherited: Object.freeze([]),
+    workspaceTargets: Object.freeze([]),
+    inspectionStatus: String(options.inspectionStatus || ''),
+    missingWorkspaceIds: Object.freeze([]),
+    selectionMode: selection.mode,
+    requestedWorkspaceIds: selection.ids,
+    workspaceAliases: Object.freeze([...workspaceAliases.entries()].map(([parentWorkspaceId, currentWorkspaceId]) => Object.freeze({ parentWorkspaceId, currentWorkspaceId }))),
+    boundary: selection.mode === 'none'
+      ? 'Package-parent carrier lineage was supplied without an explicit package-parent Workspace reuse selection; no parent Workspace source was carried. Qualified parent Workspace providers, when available, are read-only requirement-material sources only.'
+      : 'No explicitly selected package-parent Workspace provider reuse was required.'
+  });
 }
 function normalizeId(value = '') { return String(value || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''); }
 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'; }