@tiinex/core 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.25.0",
+  "version": "0.27.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": "387532b237387d95bd1a491eba1190b57ed73051",
+  "gitHead": "a7e75e17b1b95c022875c2006d2957d8cce580ae",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "387532b237387d95bd1a491eba1190b57ed73051",
-    "sourceTree": "e1a4ae2d3cc2fa91b1a734890d09af3758826617",
+    "sourceCommit": "a7e75e17b1b95c022875c2006d2957d8cce580ae",
+    "sourceTree": "e86d119618fcd9cdc48bff5b016546f79bb7bcaa",
     "repository": "Tiinex/core",
-    "previousVersion": "0.24.0"
+    "previousVersion": "0.26.0"
   }
 }

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

@@ -0,0 +1,108 @@
+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 bootstrapPaths = recoveryBootstrapArtifactPaths(bundle, inspection);
+  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: bootstrapPaths[0] || '' }),
+    ignoredFindingCodes: Object.freeze([]),
+    blockingFindingCodes: Object.freeze([]),
+    boundary: boundary()
+  });
+
+  const bootstrapArtifacts = bootstrapPaths.map((artifactPath) => Object.freeze({ artifactPath, file: findFile(bundle, artifactPath) })).filter((item) => item.artifactPath);
+  const payloadPaths = [...new Set(bootstrapArtifacts.flatMap((item) => {
+    if (!item.file) return [];
+    const markdown = decodeUtf8(packageFileBytes(item.file));
+    const target = recoveryPayloadPath(markdown);
+    return target ? [target] : [];
+  }))];
+  const bootstrapOwnedPaths = new Set([...bootstrapPaths, ...payloadPaths].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;
+  const primaryPath = bootstrapPaths.find((artifactPath) => Boolean(findFile(bundle, artifactPath))) || bootstrapPaths[0] || '';
+  return freeze({
+    schema: 'tiinex.portable.bootstrap-recovery.v1',
+    state: eligible ? 'eligible' : 'ineligible',
+    eligibleWithQualifiedHostBootstrap: eligible,
+    packageBootstrap: Object.freeze({
+      state: primaryPath ? (findFile(bundle, primaryPath) ? 'unqualified' : 'missing') : 'undeclared',
+      artifactPath: primaryPath,
+      artifactCandidates: Object.freeze([...bootstrapPaths]),
+      payloadPath: payloadPaths[0] || '',
+      payloadCandidates: Object.freeze([...payloadPaths])
+    }),
+    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 recoveryBootstrapArtifactPaths(bundle = {}, inspection = {}) {
+  const out = [];
+  const declared = String(inspection.packageContract?.bootstrapPath || '').trim();
+  if (declared) out.push(declared);
+
+  // Recovery may need to operate precisely when the bootstrap External Payload
+  // no longer qualifies strongly enough to reach normal package-contract
+  // projection. Use only explicit package-local bootstrap references from the
+  // already-identified package root/Start artifacts as recovery hints. These
+  // hints bound malformed bootstrap bytes; they do not grant bootstrap authority.
+  const candidates = [inspection.rootArtifact?.path, inspection.readArtifact?.path]
+    .map((value) => String(value || '').trim())
+    .filter(Boolean);
+  for (const artifactPath of candidates) {
+    const file = findFile(bundle, artifactPath);
+    if (!file) continue;
+    const markdown = decodeUtf8(packageFileBytes(file));
+    for (const target of explicitBootstrapMarkdownTargets(markdown)) out.push(target);
+  }
+  return Object.freeze([...new Set(out.filter(Boolean))]);
+}
+
+function explicitBootstrapMarkdownTargets(markdown = '') {
+  const out = [];
+  for (const line of String(markdown || '').split(/\r?\n/)) {
+    if (!/bootstrap/i.test(line)) continue;
+    for (const match of line.matchAll(/\[[^\]]+\]\(([^)]+\.md)\)/ig)) if (match?.[1]) out.push(match[1].trim());
+  }
+  return [...new Set(out.filter(Boolean))];
+}
+
+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);