@tiinex/core 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Shared host-neutral Tiinex implementation core for artifacts, schemas, validation, lineage, grounding, Handoffs, provenance and deterministic workflows.",
   "type": "module",
   "sideEffects": true,
@@ -173,12 +173,12 @@
     "type": "git",
     "url": "git+https://github.com/Tiinex/core.git"
   },
-  "gitHead": "c9a902017994156ce1c45f9ea78612875a072a1b",
+  "gitHead": "7a4c0e1eab27559eef417cf5eb1c15d47483d199",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "c9a902017994156ce1c45f9ea78612875a072a1b",
-    "sourceTree": "55c92c3bb3f604746613e64bd9adbe14f3fad3a1",
+    "sourceCommit": "7a4c0e1eab27559eef417cf5eb1c15d47483d199",
+    "sourceTree": "bb24af76e471a711fff58602ac0dc879c016f3a5",
     "repository": "Tiinex/core",
-    "previousVersion": "0.23.0"
+    "previousVersion": "0.25.0"
   }
 }

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

@@ -198,7 +198,28 @@ async function prepareWorkspaceCarrierCliCommand(flags = {}, workspaceRoot = '.'
   const workspaceScopeValue = await readOptionalJson(flags['workspace-scopes']);
   const additionalWorkspaces = [...splitFlag(flags['additional-workspaces']), ...descriptorArray(workspaceDescriptorValue, 'workspaces')];
   const verifyRoundtrip = !flags['no-roundtrip'];
-  const carrierProfile = selectCarrierProfile({ operator: operatorCarrierProfile, runtime: runtime.defaultCarrierProfile || null });
+  const parentPackagePath = String(flags['package-parent'] || '').trim();
+  let carrierLineage = Object.freeze({ ...initialHandoffCarrierLineage(), checkpointKind: 'progression', majorReason: '' });
+  let inheritedCarrierProfile = normalizeHandoffCarrierProfile(null);
+  if (parentPackagePath) {
+    const resolvedParent = path.resolve(parentPackagePath);
+    const parentBytes = new Uint8Array(await readFile(resolvedParent));
+    const parentBundle = await loadNodePortableInput([resolvedParent], { maxFiles: flags['max-files'], maxTextBytes: flags['max-text-bytes'] });
+    inheritedCarrierProfile = parentHandoffCarrierProfileFromBundle(parentBundle);
+    const parentLineage = parentHandoffCarrierLineageFromBundle(parentBundle);
+    carrierLineage = carrierLineageFromCliParent({
+      bundle: parentBundle,
+      parentPath: resolvedParent,
+      parentBytes,
+      qualifiedParentLineage: parentLineage,
+      major: Boolean(flags['package-major']),
+      majorReason: flags['major-reason'] || '',
+      siblingIndex: 1
+    });
+  } else if (flags['package-major']) {
+    throw new Error('portable.cli.workspace-carrier.package-major.parent-required');
+  }
+  const carrierProfile = selectCarrierProfile({ operator: operatorCarrierProfile, inherited: inheritedCarrierProfile, runtime: runtime.defaultCarrierProfile || null });
   const projectedFilename = String(flags['projected-filename'] || flags.projectedFilename || '').trim();
   const input = await prepareNodeWorkspaceCarrierManufacturingInput({
     workspaceRoot,
@@ -216,7 +237,7 @@ async function prepareWorkspaceCarrierCliCommand(flags = {}, workspaceRoot = '.'
     verifyRoundtrip,
     createdAt: flags['built-at'] || undefined,
     projectedFilename,
-    carrierLineage: Object.freeze({ ...initialHandoffCarrierLineage(), checkpointKind: 'progression', majorReason: '' }),
+    carrierLineage,
     carrierProfile
   }, runtime);
   return { input, options: { verifyRoundtrip, packageInput: { builtAt: flags['built-at'] || undefined } } };

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

@@ -0,0 +1,70 @@
+import { packageFileBytes } from '../../../export/package.bytes.js';
+
+const BOOTSTRAP_CODE_PREFIXES = Object.freeze([
+  'portable.handoff-package-v1.bootstrap-',
+  'portable.handoff-v2-surface.bootstrap.',
+  'portable.tooling-bootstrap.'
+]);
+
+export function projectPortableBootstrapRecovery(bundle = {}, inspection = {}) {
+  const findings = Array.isArray(inspection.findings) ? inspection.findings : [];
+  const errors = findings.filter((item) => String(item?.severity || '') === 'error');
+  const bootstrapPath = String(inspection.packageContract?.bootstrapPath || '').trim();
+  const packageBootstrapValid = String(inspection.bootstrapInspection?.status || '') === 'valid';
+  if (packageBootstrapValid) return freeze({
+    schema: 'tiinex.portable.bootstrap-recovery.v1',
+    state: 'not-needed',
+    eligibleWithQualifiedHostBootstrap: false,
+    packageBootstrap: Object.freeze({ state: 'qualified', artifactPath: bootstrapPath }),
+    ignoredFindingCodes: Object.freeze([]),
+    blockingFindingCodes: Object.freeze([]),
+    boundary: boundary()
+  });
+
+  const bootstrapArtifact = bootstrapPath ? findFile(bundle, bootstrapPath) : null;
+  const bootstrapMarkdown = bootstrapArtifact ? decodeUtf8(packageFileBytes(bootstrapArtifact)) : '';
+  const payloadPath = bootstrapMarkdown ? recoveryPayloadPath(bootstrapMarkdown) : '';
+  const bootstrapOwnedPaths = new Set([bootstrapPath, payloadPath].filter(Boolean));
+  const ignored = [];
+  const blocking = [];
+  for (const item of errors) {
+    const code = String(item?.code || '');
+    const findingPath = String(item?.path || item?.packagePath || '').trim();
+    const bootstrapScoped = BOOTSTRAP_CODE_PREFIXES.some((prefix) => code.startsWith(prefix)) || (findingPath && bootstrapOwnedPaths.has(findingPath));
+    (bootstrapScoped ? ignored : blocking).push(item);
+  }
+
+  const packageStructurePresent = Boolean(inspection.rootArtifact && inspection.readArtifact && inspection.carrierProjection);
+  const carrierReady = String(inspection.carrierProjection?.status || '') === 'ready';
+  const eligible = packageStructurePresent && carrierReady && ignored.length > 0 && blocking.length === 0;
+  return freeze({
+    schema: 'tiinex.portable.bootstrap-recovery.v1',
+    state: eligible ? 'eligible' : 'ineligible',
+    eligibleWithQualifiedHostBootstrap: eligible,
+    packageBootstrap: Object.freeze({
+      state: bootstrapPath ? (bootstrapArtifact ? 'unqualified' : 'missing') : 'undeclared',
+      artifactPath: bootstrapPath,
+      payloadPath
+    }),
+    ignoredFindingCodes: Object.freeze(ignored.map((item) => String(item?.code || '')).filter(Boolean)),
+    blockingFindingCodes: Object.freeze(blocking.map((item) => String(item?.code || '')).filter(Boolean)),
+    boundary: boundary()
+  });
+}
+
+function recoveryPayloadPath(markdown = '') {
+  const lines = String(markdown || '').split(/\r?\n/);
+  for (const line of lines) {
+    if (!/(?:payload|location)/i.test(line)) continue;
+    const link = line.match(/\[[^\]]+\]\(([^)]+\.zip)\)/i);
+    if (link?.[1]) return link[1].trim();
+    const field = line.match(/(?:Payload Path|Payload|Location|Bootstrap Payload)\s*:\s*`?([^`\s]+\.zip)`?/i);
+    if (field?.[1]) return field[1].trim();
+  }
+  return '';
+}
+
+function findFile(bundle = {}, path = '') { return (bundle.files || []).find((file) => String(file.path || '') === String(path || '')) || null; }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function boundary() { return 'Host-bootstrap recovery is a read-only execution fallback only. It does not rewrite package bytes, qualify a broken package bootstrap, erase original findings, or create Handoff/Workspace/semantic authority.'; }
+function freeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; for (const child of Object.values(value)) freeze(child); return Object.freeze(value); }

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

@@ -3,6 +3,7 @@ import { inspectHandoffCarrierProjection } from './carrierProjection.js';
 import { inspectHandoffPointerEntrypoints } from './pointerEntrypoint.js';
 import { inspectRecipientFacingV2Topology } from './recipientV2.inspect.js';
 import { RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+import { projectPortableBootstrapRecovery } from './bootstrapRecovery.js';
 
 export const HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH = 'tiinex.package/START.md';
 export const HANDOFF_COLD_CONSUMER_PROJECTION_SCHEMA_ID = 'tiinex.portable.handoff-cold-consumer-projection.v1';
@@ -120,6 +121,7 @@ export function orientColdConsumerFromHandoffPackage(input = {}) {
   if ((bundle.files || []).some((file) => String(file.path || '') === RECIPIENT_V2_READ_PATH)) {
     const v2 = inspectRecipientFacingV2Topology(bundle);
     const projection = v2.coldConsumerProjection || null;
+    const bootstrapRecovery = projectPortableBootstrapRecovery(bundle, v2);
     const routeMetadata = new Map((v2.routes || []).map((route) => [`${String(route.workspaceId || '')}\u0000${String(route.workspaceRelativeHandoffPath || '')}`, route]));
     const carrierRouteById = new Map((v2.carrierProjection?.routes || []).map((route) => [String(route.id || ''), route]));
     const workspaceArchiveById = new Map((v2.workspaces || []).map((workspace) => {
@@ -135,7 +137,7 @@ export function orientColdConsumerFromHandoffPackage(input = {}) {
       const handoffPath = String(route.workspaceRelativeHandoffPath || '');
       return Object.freeze({ ...route, sha256: handoffSha256, sha256Target: handoffPath, handoffSha256, archiveSha256: String(archive.sha256 || ''), archivePackagePath: String(archive.path || route.packagePath || ''), requiredClosure: carrierRoute.requiredClosure || null, pointerPath: String(metadata.pointerPath || ''), endpointRolePointers: Object.freeze([...(metadata.endpointRolePointers || [])]), participantRolePointers: Object.freeze([...(metadata.participantRolePointers || [])]) });
     }));
-    return deepFreeze({ schema: 'tiinex.portable.handoff-cold-consumer-orientation.v1', status: v2.status === 'valid' && projection?.status === 'ready' ? 'ready' : 'blocked', entrypoint: Object.freeze({ schema: 'tiinex.portable.handoff-v2.recipient-orientation.inspection.v1', status: v2.status, path: RECIPIENT_V2_READ_PATH, projection, findings: v2.findings }), pointerEntrypoints: Object.freeze({ schema: 'tiinex.portable.handoff-v2.recipient-pointer.inspection.v1', status: v2.status, entries: v2.routes, findings: v2.findings }), workspaces: projection?.workspaces || Object.freeze([]), carrierLineage: v2.carrierProjection?.lineage || null, routes, endpointRoles: v2.endpointRoles || Object.freeze([]), participantRoles: v2.participantRoles || Object.freeze([]), selection: projection?.selection || null, operationBoundary: orientationOperationBoundary(v2.bootstrapInspection), boundary: 'Read-only recipient-facing v2 orientation from qualified visible Tiinex artifacts and exact payload bytes; no legacy control JSON, filename, or adjacency authority.' });
+    return deepFreeze({ schema: 'tiinex.portable.handoff-cold-consumer-orientation.v1', status: v2.status === 'valid' && projection?.status === 'ready' ? 'ready' : 'blocked', entrypoint: Object.freeze({ schema: 'tiinex.portable.handoff-v2.recipient-orientation.inspection.v1', status: v2.status, path: RECIPIENT_V2_READ_PATH, projection, findings: v2.findings }), pointerEntrypoints: Object.freeze({ schema: 'tiinex.portable.handoff-v2.recipient-pointer.inspection.v1', status: v2.status, entries: v2.routes, findings: v2.findings }), workspaces: projection?.workspaces || Object.freeze([]), carrierLineage: v2.carrierProjection?.lineage || null, routes, endpointRoles: v2.endpointRoles || Object.freeze([]), participantRoles: v2.participantRoles || Object.freeze([]), selection: projection?.selection || null, bootstrapRecovery, operationBoundary: orientationOperationBoundary(v2.bootstrapInspection), boundary: 'Read-only recipient-facing v2 orientation from qualified visible Tiinex artifacts and exact payload bytes; no legacy control JSON, filename, or adjacency authority.' });
   }
   const inspection = inspectHandoffColdConsumerEntrypoint(bundle);
   const pointerEntrypoints = inspectHandoffPointerEntrypoints(bundle);