@tiinex/core 0.1.1 → 0.3.0

package/README.md

@@ -31,15 +31,15 @@ Source paths intentionally follow the same `src/...` conventions used by other T
 repositories where the concepts match. npm distribution preserves this source layout
 rather than inventing a second directory vocabulary.
 
-## This source checkpoint
+## Current implementation frontier
 
-Not yet release-qualified. The public packages are tested headlessly from local npm archives. A full dependency-equipped React/Vite bundle and rendered external-Verse acceptance remain pending. Publishing is disabled in `.github/release-policy.json`.
+`@tiinex/core` is a published package boundary; package publication does not by itself establish browser/product acceptance or semantic authority. App/Site/Verse integration remains separately qualified by those consumers.
 
-The explicit package export map also exposes the shared module paths used by App. These preserve the mirrored layout, not a second implementation. `tools/tiinex-portable.mjs` is retained as the existing bootstrap entrypoint until the later CLI/Interop extraction.
+The explicit package export map exposes the shared module paths used by App. These preserve the mirrored layout, not a second implementation. `tools/tiinex-portable.mjs` remains a transitional compatibility entrypoint while dedicated CLI/Interop hosts are stabilized. See [`docs/ARCHITECTURE-BOUNDARIES.md`](docs/ARCHITECTURE-BOUNDARIES.md) for the carrier-bootstrap, schema-material and external-Interop split.
 
 Application data is a declared-data projection: parsing and exact reference resolution are not schema validation, integrity verification or authority qualification. Missing Parent evidence remains unresolved. Companion byte access belongs to registered host readers, not automatic filesystem or network permissions.
 
 
-## 2026-09-08 integration frontier
+## npm release frontier
 
-Master-only automatic versioning/publication is implemented through the single Core Node release helper. See `docs/NPM-PUBLISH.md`; release is disabled until `TIINEX_ENABLE_NPM_PUBLISH` and the npm environment are configured. No registry publication was performed by Anchor.
+Master-only automatic versioning/publication is implemented through the Core Node release helper. See `docs/NPM-PUBLISH.md`. OIDC/Trusted Publisher configuration is an external repository/package setting and remains separate from source qualification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Shared host-neutral Tiinex implementation core for artifacts, schemas, validation, lineage, grounding, Handoffs, provenance and deterministic workflows.",
   "type": "module",
   "sideEffects": true,
@@ -165,12 +165,12 @@
     "type": "git",
     "url": "git+https://github.com/Tiinex/core.git"
   },
-  "gitHead": "9157bef33d676549db915dcb229ecdbf371b748f",
+  "gitHead": "24c0ac44dcab14259b3adee85fa83434a462f9dc",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "9157bef33d676549db915dcb229ecdbf371b748f",
-    "sourceTree": "b425dc2882772dce03472d63563ab2e481c2b1b5",
+    "sourceCommit": "24c0ac44dcab14259b3adee85fa83434a462f9dc",
+    "sourceTree": "cbf5f25e875efac11c017d9914efa673bdfc2edb",
     "repository": "Tiinex/core",
-    "previousVersion": null
+    "previousVersion": "0.2.0"
   }
 }

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

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseArtifactMarkdown } from '../../../../artifacts/artifact.parse.js';
 import { buildArtifactCreationContract } from '../../../../schemas/creation.contracts.js';
@@ -8,6 +8,7 @@ import { sha256Hex, utf8Bytes } from '../../../../export/package.bytes.js';
 import { resolveSchemaModule } from '../../../../schemas/resolver.js';
 import { loadNodePortableInput } from '../../input/node.input.js';
 import { runPortableOperation } from '../../operation.catalog.js';
+import { allocateContinuationPath, allocateDirectoryArtifactPath } from '../../../../transitions/record.transitions.js';
 
 const STATE_RELATIVE_PATH = '.tiinex/continuation.json';
 
@@ -16,21 +17,27 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
   const workspaceRoot = path.resolve(String(flags.workspace || parsed.positionals?.[0] || '.'));
   const state = await readContinuationState(workspaceRoot);
   const schemaId = String(flags.schema || '').trim();
-  const artifactRelativePath = normalizeWorkspaceRelativePath(flags.path || parsed.positionals?.[1] || '');
+  const requestedArtifactRelativePath = normalizeWorkspaceRelativePath(flags.path || parsed.positionals?.[1] || '');
+  const targetDirectory = normalizeWorkspaceRelativePath(flags.directory || flags.dir || '');
   const bodyPath = String(flags.body || flags.content || '').trim();
   if (!schemaId) throw new Error('portable.cli.author.schema.required');
-  if (!artifactRelativePath) throw new Error('portable.cli.author.path.required');
+  if (!requestedArtifactRelativePath && !targetDirectory) throw new Error('portable.cli.author.path-or-directory.required');
   if (!bodyPath) throw new Error('portable.cli.author.body.required');
-  const artifactPath = safeWorkspaceTarget(workspaceRoot, artifactRelativePath);
   const bodyMarkdown = (await readFile(path.resolve(bodyPath), 'utf8')).trim();
   if (!bodyMarkdown) throw new Error('portable.cli.author.body.empty');
+  const title = String(flags.title || firstHeading(bodyMarkdown) || state?.roleLabel || schemaId).trim();
 
-  const parentRelativePath = resolveParentRelativePath(flags, state);
-  const parentPath = parentRelativePath ? safeWorkspaceTarget(workspaceRoot, parentRelativePath) : '';
-  const parentRecord = parentPath ? await parentRecordFromArtifact(parentPath, parentRelativePath, { workspaceRoot, childRelativePath: artifactRelativePath }) : {};
+  const parentReference = resolveParentReference(flags, state);
+  const parentSource = String(flags['parent-source'] || flags['parent-file'] || '').trim();
+  if (isWorkspaceQualifiedReference(parentReference) && !parentSource) throw new Error('portable.cli.author.parent-source.required');
+  if (parentSource && !parentReference) throw new Error('portable.cli.author.parent.required');
+  if (isWorkspaceQualifiedReference(parentReference) && !requestedArtifactRelativePath && !targetDirectory) throw new Error('portable.cli.author.cross-workspace-parent.target-required');
+  const parentPath = parentReference ? (parentSource ? path.resolve(parentSource) : safeWorkspaceTarget(workspaceRoot, parentReference)) : '';
+  const artifactRelativePath = requestedArtifactRelativePath || await allocateArtifactRelativePath({ workspaceRoot, targetDirectory, parentRelativePath: parentReference, schemaId, title });
+  const artifactPath = safeWorkspaceTarget(workspaceRoot, artifactRelativePath);
+  const parentRecord = parentPath ? await parentRecordFromArtifact(parentPath, parentReference, { workspaceRoot, childRelativePath: artifactRelativePath }) : {};
   const transitionType = String(flags.transition || defaultTransition(schemaId, Boolean(parentPath))).trim();
   const contract = buildArtifactCreationContract({ schemaId, transitionType });
-  const title = String(flags.title || firstHeading(bodyMarkdown) || state?.roleLabel || schemaId).trim();
   const summary = String(flags.summary || title).trim();
   const authors = String(flags.authors || state?.roleLabel || '').trim();
   const why = Object.prototype.hasOwnProperty.call(flags, 'why') ? String(flags.why || '').trim() : '';
@@ -94,7 +101,7 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
       schema: 'tiinex.portable.common-author.result.v1',
       operation: 'author',
       status: 'qualified',
-      artifact: Object.freeze({ path: artifactRelativePath, absolutePath: artifactPath, schemaId, parentPath: parentRelativePath, selfIntegrity: selfIntegrity.state, written: true }),
+      artifact: Object.freeze({ path: artifactRelativePath, absolutePath: artifactPath, schemaId, parentPath: parentReference, parentSource: parentSource || '', selfIntegrity: selfIntegrity.state, written: true }),
       qualification: Object.freeze({ audit: audit.status, stage: stage.status, exportReady: Boolean(stage?.stagedArtifact?.qualification?.exportReady) }),
       findingSummary: mergeFindingSummaries(audit?.findingSummary, stage?.findingSummary),
       nextAction: schemaId === 'tiinex.handoff.v1'
@@ -186,12 +193,62 @@ async function recoverQualifiedLocalSchemaReferenceAuthority(schemaId, context =
   });
 }
 
-function resolveParentRelativePath(flags = {}, state = {}) {
+async function allocateArtifactRelativePath({ workspaceRoot, targetDirectory, parentRelativePath, schemaId, title } = {}) {
+  const directory = normalizeWorkspaceRelativePath(targetDirectory || (parentRelativePath ? path.posix.dirname(parentRelativePath) : '.topics')) || '.topics';
+  const existingPaths = await directoryArtifactPaths(workspaceRoot, directory);
+  const allocation = parentRelativePath
+    ? allocateContinuationPath({ parentRecord: { path: parentRelativePath }, targetId: schemaId, targetLabel: labelFromSchemaId(schemaId), title }, { targetDirectory: directory, existingPaths })
+    : allocateDirectoryArtifactPath({ targetDirectory: directory, targetId: schemaId, targetLabel: labelFromSchemaId(schemaId), title }, { existingPaths });
+  const allocated = normalizeWorkspaceRelativePath(allocation?.path || '');
+  if (!allocated) throw new Error('portable.cli.author.allocation.unavailable');
+  return allocated;
+}
+
+async function directoryArtifactPaths(workspaceRoot, directory) {
+  const dirPath = safeWorkspaceDirectory(workspaceRoot, directory);
+  let entries = [];
+  try { entries = await readdir(dirPath, { withFileTypes: true }); }
+  catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+  return entries.filter((entry) => entry.isFile()).map((entry) => `${directory}/${entry.name}`);
+}
+
+function safeWorkspaceDirectory(root, relative) {
+  const normalized = normalizeWorkspaceRelativePath(relative || '.topics') || '.topics';
+  const target = path.resolve(root, normalized);
+  const rel = path.relative(root, target);
+  if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error(`portable.cli.author.directory.unsafe:${relative}`);
+  return target;
+}
+
+function labelFromSchemaId(id = '') {
+  const tail = String(id || '').split('.').filter(Boolean).slice(-2, -1)[0] || String(id || 'artifact');
+  return tail.charAt(0).toUpperCase() + tail.slice(1);
+}
+
+function resolveParentReference(flags = {}, state = {}) {
   if (flags['no-parent']) return '';
-  if (typeof flags.parent === 'string' && flags.parent.trim()) return normalizeWorkspaceRelativePath(flags.parent);
+  if (typeof flags.parent === 'string' && flags.parent.trim()) return normalizeParentReference(flags.parent);
   return normalizeWorkspaceRelativePath(state?.lastAuthoredPath || state?.selectedHandoffPath || '');
 }
 
+export function normalizeParentReference(value = '') {
+  const raw = String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!raw || raw.startsWith('/') || /^[A-Za-z]:\//.test(raw)) return '';
+  const marker = raw.indexOf('::');
+  if (marker < 0) return normalizeWorkspaceRelativePath(raw);
+  const workspaceId = raw.slice(0, marker).trim();
+  const innerPath = normalizeWorkspaceRelativePath(raw.slice(marker + 2));
+  if (!workspaceId || !/^[A-Za-z0-9._-]+$/.test(workspaceId) || !innerPath) return '';
+  return `${workspaceId}::${innerPath}`;
+}
+
+function isWorkspaceQualifiedReference(value = '') {
+  return /^[A-Za-z0-9._-]+::/.test(String(value || ''));
+}
+
 function defaultTransition(schemaId, hasParent) {
   if (!hasParent) return 'create-artifact';
   if (schemaId === 'tiinex.evidence.v1') return 'reference-record';

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 packageParentWorkspaceAliases = await readOptionalJson(flags['package-parent-workspace-aliases']);
   const operatorCarrierProfile = await readOptionalJson(flags['carrier-profile']);
   const expectedToolingBootstrap = await readOptionalJson(flags['tooling-bootstrap-manifest']);
   const workspaceDescriptorValue = await readOptionalJson(flags['workspace-roots'] || flags['workspace-descriptors']);
@@ -124,7 +125,8 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
     carrierProfile,
     packageParentBundle,
     packageParentPath: parentPackagePath ? path.resolve(parentPackagePath) : '',
-    packageParentSha256
+    packageParentSha256,
+    packageParentWorkspaceAliases
   }, runtime);
   return {
     input,

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

@@ -10,7 +10,7 @@ export function portableCliHelpText(commandPrefix = '', surfaceCommand = '') {
     'Common path (same command for humans and LLMs):',
     `${command} ground <handoff-package.zip> --route <Continue-from> [--holder-role <recipient-role>]`,
     `${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> --body <body.md> [--parent <workspace-relative-parent>] [--title <title>] [--summary <summary>] [--why <why>]`,
+    `${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>`,
     '',
     `Handoff aliases: ${command} orient <carrier.zip>; ${command} validate <carrier.zip>`,
@@ -20,7 +20,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. 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. 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.',
     '- 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.'
@@ -43,9 +43,9 @@ function commonCommandHelp(command, surfaceCommand) {
   if (surfaceCommand === 'author') return [
     'Tiinex portable tooling — author',
     '',
-    `${command} author <workspace-dir> --schema <schema-id> --path <workspace-relative-artifact> --body <body.md> [--parent <workspace-relative-parent>] [--title <title>] [--summary <summary>] [--why <why>]`,
+    `${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>]`,
     '',
-    'Uses qualified continuation state to infer the ordinary Parent when `--parent` is omitted, seals c14n-v2 self-integrity, audits, stages, and updates continuation state only after qualification. Invalid output is not retained.',
+    'Uses qualified continuation state to infer the ordinary Parent when `--parent` is omitted. Supply `--path` for an exact requested coordinate or `--directory` to let Tooling allocate inside that directory-local filename namespace. For a Workspace-qualified Parent such as `business::.topics/...`, also supply `--parent-source` so Tooling reads and seals against the exact Parent bytes without treating the foreign address as a local path. Authoring seals c14n-v2 self-integrity, audits, stages, and updates continuation state only after qualification. Invalid output is not retained.',
     '',
     `Advanced/internal catalog: ${command} operations`
   ];

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

@@ -2,5 +2,6 @@ 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,6 +3,19 @@ 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/node/handoff.manufacture.js

@@ -67,7 +67,8 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     bundle: input.packageParentBundle || null,
     currentWorkspaceIds: [...seenWorkspaceIds],
     parentPackagePath: input.packageParentPath || '',
-    parentPackageSha256: input.packageParentSha256 || ''
+    parentPackageSha256: input.packageParentSha256 || '',
+    workspaceAliases: input.packageParentWorkspaceAliases || input.workspaceAliases || {}
   });
   const additionalEnumerationsPromise = Promise.all(additionalWorkspaceInputs.map(async ({ descriptor, id, root, requestedTitle }) => {
     const enumerated = await enumerateNodeWorkspace(root, {
@@ -168,6 +169,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
         state: String(packageParentReuse.state || ''),
         inspectionStatus: String(packageParentReuse.inspectionStatus || ''),
         inheritedWorkspaceIds: Object.freeze((packageParentReuse.inherited || []).map((item) => String(item.id || ''))),
+        workspaceAliases: Object.freeze([...(packageParentReuse.workspaceAliases || [])].map((item) => Object.freeze({ ...item }))),
         boundary: String(packageParentReuse.boundary || '')
       }),
       carrierProjection: Object.freeze({ requestedRoutes: transportRoutes.length || 1, carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null), carrierProfile: normalizeHandoffCarrierProfile(input.carrierProfile || null), boundary: 'Routes are qualified later against packaged workspace bytes; adapter text is not authority.' })

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

@@ -6,11 +6,13 @@ 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 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) => !currentIds.has(normalizeId(item.workspaceId)));
+  const missing = declared.filter((item) => !packageParentWorkspaceSupersededByCurrent(item.workspaceId, currentIds, workspaceAliases));
   if (!missing.length) return emptyReuse('not-needed');
 
   const providerById = new Map((inspection.workspaceByteProvider?.workspaces || []).map((item) => [normalizeId(item.id), item]));
@@ -39,7 +41,8 @@ export function preparePackageParentWorkspaceReuse(input = {}) {
     workspaceTargets: Object.freeze(workspaceTargets),
     inspectionStatus: inspection.status,
     missingWorkspaceIds: Object.freeze(missing.map((item) => normalizeId(item.workspaceId))),
-    boundary: 'Exact complete Workspace bytes reused from one independently qualified received package parent. Explicit current Workspace roots take precedence by id; parent-carrier placement and lineage remain non-semantic.'
+    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.'
   });
 }
 
@@ -121,8 +124,34 @@ function buildInheritedEnumeration(provider = {}, source = {}) {
   });
 }
 
+export function normalizePackageParentWorkspaceAliases(value = {}) {
+  const entries = Array.isArray(value)
+    ? value.map((item) => [item?.parentWorkspaceId || item?.parent || item?.from, item?.currentWorkspaceId || item?.current || item?.to])
+    : Object.entries(value || {});
+  const out = new Map();
+  const targets = new Set();
+  for (const [parentValue, currentValue] of entries) {
+    const parentWorkspaceId = normalizeId(parentValue);
+    const currentWorkspaceId = normalizeId(currentValue);
+    if (!parentWorkspaceId || !currentWorkspaceId) throw new Error('portable.handoff-manufacture.package-parent.workspace-alias.invalid');
+    if (parentWorkspaceId === currentWorkspaceId) throw new Error(`portable.handoff-manufacture.package-parent.workspace-alias.identity:${parentWorkspaceId}`);
+    if (out.has(parentWorkspaceId)) throw new Error(`portable.handoff-manufacture.package-parent.workspace-alias.duplicate-parent:${parentWorkspaceId}`);
+    if (targets.has(currentWorkspaceId)) throw new Error(`portable.handoff-manufacture.package-parent.workspace-alias.duplicate-target:${currentWorkspaceId}`);
+    out.set(parentWorkspaceId, currentWorkspaceId);
+    targets.add(currentWorkspaceId);
+  }
+  return out;
+}
+
+export function packageParentWorkspaceSupersededByCurrent(parentWorkspaceId = '', currentWorkspaceIds = new Set(), workspaceAliases = new Map()) {
+  const id = normalizeId(parentWorkspaceId);
+  if (currentWorkspaceIds.has(id)) return true;
+  const replacement = workspaceAliases.get(id) || '';
+  return Boolean(replacement && currentWorkspaceIds.has(replacement));
+}
+
 function emptyReuse(state) {
-  return Object.freeze({ state, inherited: Object.freeze([]), workspaceTargets: Object.freeze([]), inspectionStatus: '', missingWorkspaceIds: Object.freeze([]), boundary: 'No package-parent Workspace provider reuse was required.' });
+  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 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'; }

package/src/tooling/portable/handoff/sourceFrontierComparison.js

@@ -0,0 +1,186 @@
+import path from 'node:path';
+import { access, readFile, readdir } from 'node:fs/promises';
+import { sha256Hex } from '../../../export/package.bytes.js';
+import { inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
+import { parseHandoffPackageV1 } from './recipientV2.packageV1.contract.js';
+import { currentSchemaId, decodeUtf8, deepFreeze, dedupeFindings } from './recipientV2.packageV1.shared.js';
+import { finding } from './recipientV2.topology.materials.js';
+
+export async function compareSourceFrontiers(input = {}) {
+  const leftKind = String(input.leftKind || '').trim();
+  const rightKind = String(input.rightKind || '').trim();
+  const leftRoot = String(input.left || '').trim();
+  const rightPath = String(input.right || '').trim();
+  const workspaceId = String(input.rightSelect || input.leftId || '').trim();
+  const findings = [];
+
+  if (leftKind !== 'local-workspace') findings.push(finding('error', 'portable.source-frontier.left-kind-invalid', 'Source frontier comparison requires a local workspace on the left side.', { observed: leftKind }));
+  if (rightKind !== 'handoff-package') findings.push(finding('error', 'portable.source-frontier.right-kind-invalid', 'Source frontier comparison requires a handoff package on the right side.', { observed: rightKind }));
+  if (!leftRoot) findings.push(finding('error', 'portable.source-frontier.left-missing', 'Source frontier comparison requires a local workspace root.', { side: 'left' }));
+  if (!rightPath) findings.push(finding('error', 'portable.source-frontier.right-missing', 'Source frontier comparison requires a handoff package path.', { side: 'right' }));
+  if (!workspaceId) findings.push(finding('error', 'portable.source-frontier.workspace-id-missing', 'Source frontier comparison requires a selected workspace id.', { side: 'right-select' }));
+  if (findings.length) return blocked(findings);
+
+  try {
+    await access(leftRoot);
+  } catch {
+    findings.push(finding('error', 'portable.source-frontier.left-unavailable', 'The local workspace root is not available.', { path: leftRoot }));
+    return blocked(findings);
+  }
+
+  let packageBytes;
+  try {
+    packageBytes = await readFile(rightPath);
+  } catch {
+    findings.push(finding('error', 'portable.source-frontier.right-unavailable', 'The handoff package path is not available.', { path: rightPath }));
+    return blocked(findings);
+  }
+
+  const packageArchive = inspectStoredWorkspaceArchive(packageBytes, { ownedBytes: true });
+  if (packageArchive.state !== 'qualified') {
+    findings.push(finding('error', 'portable.source-frontier.package-unqualified', 'The supplied handoff package is not a qualified stored ZIP archive.', { path: rightPath }));
+    findings.push(...packageArchive.findings);
+    return blocked(findings);
+  }
+
+  const rootEntry = (packageArchive.entries || []).find((entry) => currentSchemaId(decodeUtf8(entry.data)) === 'tiinex.handoff.package.v1') || null;
+  if (!rootEntry) {
+    findings.push(finding('error', 'portable.source-frontier.package-root-missing', 'The handoff package does not expose a readable package-v1 root artifact.', { path: rightPath }));
+    return blocked(findings);
+  }
+
+  const packageRoot = parseHandoffPackageV1(decodeUtf8(rootEntry.data));
+  const binding = (packageRoot.workspaces || []).find((item) => String(item.workspaceId || '') === workspaceId) || null;
+  if (!binding) {
+    findings.push(finding('error', 'portable.source-frontier.workspace-missing', 'The selected workspace id is not bound by the supplied handoff package.', { workspaceId }));
+    return blocked(findings);
+  }
+  if (!binding.snapshotPath) {
+    findings.push(finding('error', 'portable.source-frontier.snapshot-path-missing', 'The selected workspace binding does not declare a snapshot path.', { workspaceId }));
+    return blocked(findings);
+  }
+
+  const packageEntries = indexEntries(packageArchive.entries || []);
+  const snapshotEntry = packageEntries.get(binding.snapshotPath) || null;
+  if (!snapshotEntry) {
+    findings.push(finding('error', 'portable.source-frontier.snapshot-missing', 'The selected workspace snapshot is not present in the supplied handoff package.', { workspaceId, path: binding.snapshotPath }));
+    return blocked(findings);
+  }
+
+  const snapshotArchive = inspectStoredWorkspaceArchive(snapshotEntry.data, { ownedBytes: true });
+  if (snapshotArchive.state !== 'qualified') {
+    findings.push(finding('error', 'portable.source-frontier.snapshot-unqualified', 'The selected workspace snapshot is not a qualified stored ZIP archive.', { workspaceId, path: binding.snapshotPath }));
+    findings.push(...snapshotArchive.findings);
+    return blocked(findings);
+  }
+
+  const localFiles = await collectLocalFiles(leftRoot);
+  const snapshotFiles = collectArchiveFiles(snapshotArchive.entries || []);
+  const comparison = compareFileSets(localFiles, snapshotFiles);
+  const state = comparison.counts.total === 0 ? 'exact' : 'changed';
+
+  return deepFreeze({
+    schema: 'tiinex.portable.source-frontier.compare.v1',
+    status: 'ready',
+    state,
+    mode: 'two-way',
+    workspaces: Object.freeze([
+      Object.freeze({
+        workspaceId,
+        state,
+        delta: Object.freeze({
+          counts: Object.freeze(comparison.counts),
+          added: Object.freeze(comparison.added),
+          removed: Object.freeze(comparison.removed),
+          byteChanged: Object.freeze(comparison.byteChanged)
+        })
+      })
+    ]),
+    findings: Object.freeze([]),
+    boundary: 'Compares one local workspace root against the exact carried workspace snapshot bytes bound by a recipient-facing handoff package. It reports only file addition, removal, and byte-change counts and fails closed when the selected workspace binding or snapshot archive is unavailable.'
+  });
+}
+
+function blocked(findings = []) {
+  const all = dedupeFindings(findings);
+  return deepFreeze({
+    schema: 'tiinex.portable.source-frontier.compare.v1',
+    status: 'blocked',
+    state: 'blocked',
+    mode: 'two-way',
+    workspaces: Object.freeze([]),
+    findings: Object.freeze(all),
+    boundary: 'Source frontier comparison failed closed before any comparison result was emitted.'
+  });
+}
+
+async function collectLocalFiles(root, current = root, prefix = '') {
+  const files = [];
+  const entries = await readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!prefix && entry.name === '.git') continue;
+    const relative = normalizePath(prefix ? `${prefix}/${entry.name}` : entry.name);
+    const absolute = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await collectLocalFiles(root, absolute, relative);
+      files.push(...nested);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const data = await readFile(absolute);
+    files.push(Object.freeze({ path: relative, bytes: data.byteLength, sha256: sha256Hex(data) }));
+  }
+  return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function collectArchiveFiles(entries = []) {
+  return entries
+    .filter((entry) => !isIgnoredPath(entry.path || ''))
+    .map((entry) => Object.freeze({ path: normalizePath(entry.path || ''), bytes: Number(entry.bytes || 0), sha256: String(entry.sha256 || '').toLowerCase() }))
+    .filter((entry) => entry.path)
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function compareFileSets(left = [], right = []) {
+  const leftByPath = new Map(left.map((entry) => [entry.path, entry]));
+  const rightByPath = new Map(right.map((entry) => [entry.path, entry]));
+  const paths = [...new Set([...leftByPath.keys(), ...rightByPath.keys()])].sort();
+  const added = [];
+  const removed = [];
+  const byteChanged = [];
+
+  for (const filePath of paths) {
+    const local = leftByPath.get(filePath) || null;
+    const remote = rightByPath.get(filePath) || null;
+    if (!local && remote) { added.push(filePath); continue; }
+    if (local && !remote) { removed.push(filePath); continue; }
+    if (local && remote && (local.bytes !== remote.bytes || local.sha256 !== remote.sha256)) byteChanged.push(filePath);
+  }
+
+  return {
+    added,
+    removed,
+    byteChanged,
+    counts: {
+      added: added.length,
+      removed: removed.length,
+      byteChanged: byteChanged.length,
+      total: added.length + removed.length + byteChanged.length
+    }
+  };
+}
+
+function indexEntries(entries = []) {
+  const index = new Map();
+  for (const entry of entries) index.set(normalizePath(entry.path || ''), entry);
+  return index;
+}
+
+function normalizePath(value = '') {
+  return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/g, '').split('/').filter((part) => part && part !== '.').join('/');
+}
+
+function isIgnoredPath(value = '') {
+  const normalized = normalizePath(value);
+  return !normalized || normalized === '.git' || normalized.startsWith('.git/');
+}

package/src/tooling/portable/operation.catalog.package.js

@@ -11,6 +11,7 @@ import { projectPortableEditorAssistance } from './editor/editor.assistance.js';
 import { projectQualifiedHandoffLeaves } from './handoff/handoffLeafProjection.js';
 import { projectPortableAuthoringParent } from './editor/authoring.parent.js';
 import { projectQualifiedWorkspacePackageSources } from './handoff/workspacePackageSources.js';
+import { compareSourceFrontiers } from './handoff/sourceFrontierComparison.js';
 import { projectPortableHandoffAuthoringPlan } from './handoff/handoffAuthoringPlan.js';
 import { projectQualifiedHandoffEndpoints } from './handoff/handoffEndpointProjection.js';
 import { projectPortableOperatorContext } from './handoff/operatorContextProjection.js';
@@ -95,6 +96,13 @@ export function createPortablePackageOperationEntries({ operation, wrapPortableR
     inputSchema: 'tiinex.portable.input.v1',
     handler: (input = {}) => wrapPortableResult('project-workspace-package-sources', projectQualifiedWorkspacePackageSources(input))
   }),
+  'compare-source-frontiers': operation({
+    name: 'compare-source-frontiers',
+    description: 'Compare one local Workspace root against one carried workspace snapshot bound by a recipient-facing Handoff package.',
+    safety: 'read-only',
+    inputSchema: 'tiinex.portable.input.v1',
+    handler: async (input = {}) => wrapPortableResult('compare-source-frontiers', await compareSourceFrontiers(input))
+  }),
   'project-handoff-authoring-plan': operation({
     name: 'project-handoff-authoring-plan',
     description: 'Project the shared root or continuation path allocation for native Handoff authoring from exact local material without creating an artifact.',

package/src/transitions/record.transitions.js

@@ -167,29 +167,59 @@ export function allocateContinuationPath({ parentRecord = {}, targetId = '', tar
   if (explicitPath) return { path: uniqueTransitionPath(explicitPath, occupied), policy: pathPolicyForExplicit(explicitPath) };
   const parentPath = externalWebArtifactUrl(parentRecord) ? '' : canonicalLocalPath(parentRecord.path || parentRecord.sourcePath || parentRecord.sourceTarget?.sourceArtifactPath || '');
   const parentDir = parentDirectory(parentPath) || '.topics';
+  const requestedDir = canonicalLocalPath(options.targetDirectory || options.directory || '');
+  const targetDir = requestedDir || parentDir;
   const parentPrefix = lineagePrefixFromPath(parentPath);
   const labelSlug = slugify(title || parentRecord.title || targetLabel || 'continuation');
   const targetSlug = slugify(targetLabel || labelFromSchemaId(targetId) || 'leaf');
   const extension = '.trace.md';
+  const directoryLocal = Boolean(requestedDir && requestedDir !== parentDir);
   const policy = {
     schema: 'tiinex.transition.path-policy.v1',
-    kind: 'same-parent-directory',
+    kind: directoryLocal ? 'directory-local-continuation' : 'same-parent-directory',
     parentDirectory: parentDir,
+    targetDirectory: targetDir,
     parentPath,
     parentLineagePrefix: parentPrefix,
     labelSlug,
     targetSlug,
-    extension
+    extension,
+    allocationAuthority: directoryLocal ? 'target-directory-local-namespace' : 'same-parent-directory-continuation'
+  };
+  return { path: pathFromPolicy(policy, occupied), policy };
+}
+
+export function allocateDirectoryArtifactPath({ targetDirectory = '.topics', targetId = '', targetLabel = '', title = '' } = {}, options = {}) {
+  const occupied = existingTransitionPaths(options);
+  const explicitPath = canonicalLocalPath(options.path || options.draftPath || '');
+  if (explicitPath) return { path: uniqueTransitionPath(explicitPath, occupied), policy: pathPolicyForExplicit(explicitPath) };
+  const dir = canonicalLocalPath(targetDirectory || '.topics') || '.topics';
+  const labelSlug = slugify(title || targetLabel || labelFromSchemaId(targetId) || 'artifact');
+  const targetSlug = slugify(targetLabel || labelFromSchemaId(targetId) || 'artifact');
+  const extension = '.trace.md';
+  const policy = {
+    schema: 'tiinex.transition.path-policy.v1',
+    kind: 'directory-local-root',
+    targetDirectory: dir,
+    labelSlug,
+    targetSlug,
+    extension,
+    allocationAuthority: 'target-directory-local-namespace'
   };
   return { path: pathFromPolicy(policy, occupied), policy };
 }
 
 function pathFromPolicy(policy = {}, occupied = new Set()) {
-  const dir = canonicalLocalPath(policy.parentDirectory || '.topics') || '.topics';
+  const kind = String(policy.kind || '').trim();
+  const dir = canonicalLocalPath(policy.targetDirectory || policy.parentDirectory || '.topics') || '.topics';
   const extension = String(policy.extension || '.trace.md').startsWith('.') ? String(policy.extension || '.trace.md') : `.${policy.extension}`;
   const labelSlug = slugify(policy.labelSlug || 'continuation');
   const targetSlug = slugify(policy.targetSlug || 'leaf');
   const parentPrefix = String(policy.parentLineagePrefix || '').trim();
+  if (kind === 'directory-local-root' || kind === 'directory-local-continuation') {
+    const rootPrefix = nextDirectoryRootLineagePrefix(dir, occupied);
+    return `${dir}/${rootPrefix}-${labelSlug}.${extension.replace(/^\./, '')}`;
+  }
   if (parentPrefix) {
     const childPrefix = nextChildLineagePrefix(parentPrefix, dir, occupied);
     return `${dir}/${childPrefix}-${labelSlug}.${extension.replace(/^\./, '')}`;
@@ -226,6 +256,25 @@ function lineagePrefixFromPath(path = '') {
   return '';
 }
 
+
+function nextDirectoryRootLineagePrefix(dir = '', occupied = new Set()) {
+  const numbers = [];
+  let width = 3;
+  for (const value of occupied || []) {
+    const canonical = canonicalLocalPath(value);
+    if (parentDirectory(canonical) !== dir) continue;
+    const name = basenameWithoutKnownMarkdownExtension(canonical);
+    const match = name.match(/^(\d+)(?:-|$)/);
+    if (!match || /^20\d{2}$/.test(match[1])) continue;
+    const root = match[1].split('-')[0];
+    if (!/^\d+$/.test(root)) continue;
+    numbers.push(Number(root));
+    width = Math.max(width, root.length);
+  }
+  const next = numbers.length ? Math.max(...numbers) + 1 : 1;
+  return String(next).padStart(width, '0');
+}
+
 function nextChildLineagePrefix(parentPrefix = '', dir = '', occupied = new Set()) {
   const prefix = String(parentPrefix || '').trim();
   const width = childOrdinalWidth(prefix);

package/src/tooling/portable/bootstrap/bootstrap.case.mjs

@@ -1,43 +0,0 @@
-import assert from 'node:assert/strict';
-import { readFile } from 'node:fs/promises';
-
-const pointer = JSON.parse(await readFile(new URL('./tiinex.llm.bootstrap.pointer.json', import.meta.url), 'utf8'));
-const bootstrap = await readFile(new URL('./tiinex.llm.bootstrap.md', import.meta.url), 'utf8');
-
-assert.equal(pointer.schema, 'tiinex.portable.bootstrap.pointer.v1');
-assert.equal(pointer.repository, 'Tiinex/site');
-assert.equal(pointer.firstOperations.includes('discover-tooling'), true);
-assert.equal(pointer.firstOperations.includes('plan-host-action'), true);
-assert.equal(pointer.boundary.remoteWrite, false);
-assert.equal(pointer.boundary.sourceMutation, false);
-assert.equal(bootstrap.includes('## Startup Modes'), true);
-assert.equal(bootstrap.includes('Pre-prompt only; no bootstrap source is loaded'), true);
-assert.equal(bootstrap.includes(pointer.bootstrapPath), true);
-assert.equal(bootstrap.includes('do not execute package code'), true);
-assert.equal(bootstrap.includes('## Bind Capabilities To Concrete Host Tools'), true);
-assert.equal(bootstrap.includes('tiinex.portable.host-action-receipt.v1'), true);
-assert.equal(bootstrap.includes('## Manufacture Recipient-Relative Handoff Packages'), true);
-assert.equal(bootstrap.includes('manufacture-handoff-package'), true);
-assert.equal(bootstrap.includes('001-1-READ-BEFORE-PROCEEDING.trace.md'), true);
-assert.equal(bootstrap.includes('001-<package-slug>.trace.md'), true);
-assert.equal(bootstrap.includes('Generated Markdown children declare package-local `Parent` continuity'), true);
-assert.equal(bootstrap.includes('Exact durable source artifacts inside Workspace/cache archives retain their own historical provenance'), true);
-assert.equal(bootstrap.includes('001-0-READ-BEFORE-PROCEEDING.trace.md'), false);
-assert.equal(bootstrap.includes('tiinex.package/START.md'), false);
-assert.equal(bootstrap.includes('orient-handoff-package'), true);
-assert.equal(bootstrap.includes('audit-handoff-package-context'), true);
-assert.equal(bootstrap.includes('inspect ./received --summary --phase-timing'), true);
-assert.equal(bootstrap.includes('audit ./received --summary --phase-timing'), true);
-assert.equal(bootstrap.includes('search-lineage ./received --query \"mobile overflow\" --relation leaf --summary --phase-timing'), true);
-assert.equal(bootstrap.includes('resolve-lineage ./received --depth 3 --direction both --summary --phase-timing'), true);
-assert.equal(bootstrap.includes('npm run tooling:search -- --query'), true);
-assert.equal(bootstrap.includes('--include-legacy-topics'), true);
-assert.equal(bootstrap.includes('--include-legacy-fixtures'), true);
-assert.equal(bootstrap.includes('ground ... --include-required-context all'), true);
-assert.equal(bootstrap.includes('A receipt that omits Required Context bodies is not proof that the model has read those bodies.'), true);
-assert.equal(bootstrap.includes('humanOutput.normalInlineRouting.content'), true);
-assert.equal(bootstrap.includes('sole primary package'), true);
-assert.equal(bootstrap.includes('Filename or co-location under a bootstrap-like path does not grant bootstrap authority.'), true);
-assert.equal(bootstrap.includes('canonical Handoff semantic authoring/validation or a locked canonical package schema'), true);
-
-console.log('✓ portable bootstrap pointer and startup-mode contract passed');