@tiinex/core 0.1.1

package/src/tooling/portable/handoff/recipientV2.transportManifest.js

@@ -0,0 +1,123 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { packageFileByteView, packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { parseRecipientV2Facts } from './recipientV2.artifacts.js';
+
+export const RECIPIENT_V2_TRANSPORT_MANIFEST_PATH = 'tiinex-recipient-v2.transport.json';
+export const RECIPIENT_V2_TRANSPORT_MANIFEST_SCHEMA_ID = 'tiinex.transport.recipient-v2.manifest.v1';
+
+export function recipientV2TransportFacts(role = '', facts = {}) {
+  return Object.freeze({ factsFormat: 'portable-recipient-v2', factsVersion: 1, role: String(role || ''), ...(facts || {}) });
+}
+
+export function buildRecipientV2TransportManifestFile(files = [], input = {}) {
+  const entries = [...files]
+    .filter((file) => String(file.path || '') !== RECIPIENT_V2_TRANSPORT_MANIFEST_PATH)
+    .map((file) => {
+      const data = packageFileByteView(file);
+      return Object.freeze({
+        path: String(file.path || ''),
+        bytes: data.byteLength,
+        sha256: reusableFinalizedIdentity(file, data) || sha256Hex(data),
+        kind: String(file.kind || ''),
+        mediaType: String(file.mediaType || ''),
+        ...(file.transportFacts ? { facts: file.transportFacts } : {})
+      });
+    })
+    .sort((a, b) => a.path.localeCompare(b.path));
+  const manifest = Object.freeze({
+    schema: RECIPIENT_V2_TRANSPORT_MANIFEST_SCHEMA_ID,
+    version: 1,
+    format: String(input.format || ''),
+    packageRootPath: String(input.packageRootPath || ''),
+    entryArtifactPath: String(input.entryArtifactPath || ''),
+    boundary: 'Transport-owned recipient-v2 topology and exact byte map. This control surface is not a Tiinex semantic artifact and does not create Parent, Workspace, Handoff, authorship, or publication authority.',
+    entries: Object.freeze(entries)
+  });
+  return finalizeFile({
+    path: RECIPIENT_V2_TRANSPORT_MANIFEST_PATH,
+    kind: 'handoff-transport-manifest',
+    logicalKind: 'recipient-v2-transport-control',
+    mediaType: 'application/json',
+    content: `${stableJson(manifest)}\n`,
+    boundary: manifest.boundary
+  });
+}
+
+export function inspectRecipientV2TransportManifest(files = [], options = {}) {
+  const findings = [];
+  const candidates = files.filter((file) => String(file.path || '') === RECIPIENT_V2_TRANSPORT_MANIFEST_PATH);
+  if (!candidates.length) return Object.freeze({ state: 'absent', file: null, manifest: null, factsByPath: new Map(), identityByPath: new Map(), findings: Object.freeze([]) });
+  if (candidates.length !== 1) return Object.freeze({ state: 'invalid', file: null, manifest: null, factsByPath: new Map(), identityByPath: new Map(), findings: Object.freeze([finding('error', 'portable.handoff-v2-transport.manifest.duplicate', 'Recipient-v2 transport manifest must occur exactly once.', { count: candidates.length })]) });
+  const file = candidates[0];
+  let manifest;
+  try { manifest = JSON.parse(decodeUtf8(packageFileBytes(file))); }
+  catch { return Object.freeze({ state: 'invalid', file, manifest: null, factsByPath: new Map(), identityByPath: new Map(), findings: Object.freeze([finding('error', 'portable.handoff-v2-transport.manifest.parse-failed', 'Recipient-v2 transport manifest is not valid JSON.')]) }); }
+  if (manifest?.schema !== RECIPIENT_V2_TRANSPORT_MANIFEST_SCHEMA_ID || Number(manifest?.version || 0) !== 1) findings.push(finding('error', 'portable.handoff-v2-transport.manifest.schema-invalid', 'Recipient-v2 transport manifest schema/version is unsupported.'));
+  if (!manifest?.format || !manifest?.packageRootPath || !manifest?.entryArtifactPath) findings.push(finding('error', 'portable.handoff-v2-transport.manifest.identity-incomplete', 'Recipient-v2 transport manifest is missing format/root/entry identity.'));
+  const physical = new Map();
+  for (const candidate of files) {
+    const path = String(candidate.path || '');
+    if (!path || path === RECIPIENT_V2_TRANSPORT_MANIFEST_PATH) continue;
+    const list = physical.get(path) || [];
+    list.push(candidate);
+    physical.set(path, list);
+  }
+  const declared = new Map();
+  const factsByPath = new Map();
+  const identityByPath = new Map();
+  for (const entry of Array.isArray(manifest?.entries) ? manifest.entries : []) {
+    const path = String(entry?.path || '');
+    if (!path || declared.has(path)) { findings.push(finding('error', 'portable.handoff-v2-transport.manifest.entry-path-invalid', 'Transport manifest entry path is missing or duplicated.', { path })); continue; }
+    declared.set(path, entry);
+    const matches = physical.get(path) || [];
+    if (matches.length !== 1) { findings.push(finding('error', 'portable.handoff-v2-transport.manifest.entry-unresolved', 'Transport manifest entry does not resolve to exactly one visible carrier.', { path, count: matches.length })); continue; }
+    const data = packageFileByteView(matches[0]);
+    const observedSha256 = reusableReceivedIdentity(options.verifiedPhysicalIdentityByPath?.get?.(path), data) || sha256Hex(data);
+    identityByPath.set(path, Object.freeze({ bytes: data.byteLength, sha256: observedSha256 }));
+    if (Number(entry.bytes) !== data.byteLength || String(entry.sha256 || '') !== observedSha256) findings.push(finding('error', 'portable.handoff-v2-transport.manifest.byte-identity-mismatch', 'Transport manifest byte identity does not match the visible carrier.', { path }));
+    if (/\.md$/i.test(path)) {
+      if (!entry.facts || entry.facts.factsFormat !== 'portable-recipient-v2' || Number(entry.facts.factsVersion || 0) !== 1) findings.push(finding('error', 'portable.handoff-v2-transport.manifest.markdown-facts-missing', 'Every generated recipient-v2 Markdown carrier requires one transport-manifest facts record.', { path }));
+      else factsByPath.set(path, Object.freeze({ ...entry.facts }));
+    } else if (entry.facts) findings.push(finding('error', 'portable.handoff-v2-transport.manifest.nonmarkdown-facts', 'Transport facts may only annotate generated Markdown carriers.', { path }));
+  }
+  for (const [path, matches] of physical) {
+    if (matches.length !== 1) findings.push(finding('error', 'portable.handoff-v2-transport.manifest.physical-duplicate', 'Visible recipient-v2 carrier path is duplicated.', { path, count: matches.length }));
+    if (!declared.has(path)) findings.push(finding('error', 'portable.handoff-v2-transport.manifest.unmapped-carrier', 'Visible recipient-v2 carrier is absent from the transport manifest byte map.', { path }));
+  }
+  return Object.freeze({ state: findings.some((item) => item.severity === 'error') ? 'invalid' : 'valid', file, manifest: manifest || null, factsByPath, identityByPath, findings: Object.freeze(findings) });
+}
+
+export function recipientV2FactsForFile(file = {}, transportInspection = null) {
+  const path = String(file?.path || '');
+  const manifested = transportInspection?.factsByPath?.get?.(path) || null;
+  if (manifested) return manifested;
+  if (!/\.md$/i.test(path)) return null;
+  return parseRecipientV2Facts(decodeUtf8(packageFileBytes(file)));
+}
+
+export function recipientV2FactsIndex(bundle = {}) {
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const transport = inspectRecipientV2TransportManifest(files);
+  const map = new Map();
+  for (const file of files) {
+    const facts = recipientV2FactsForFile(file, transport.state === 'valid' ? transport : null);
+    if (facts) map.set(String(file.path || ''), facts);
+  }
+  return Object.freeze({ transport, map });
+}
+
+function reusableFinalizedIdentity(file = {}, data = new Uint8Array()) {
+  if (!Object.isFrozen(file) || Number(file.bytes) !== data.byteLength) return '';
+  const digest = String(file.sha256 || '').toLowerCase();
+  return /^[a-f0-9]{64}$/.test(digest) ? digest : '';
+}
+function reusableReceivedIdentity(identity = null, data = new Uint8Array()) {
+  if (!identity || identity.data !== data || Number(identity.bytes) !== data.byteLength) return '';
+  const digest = String(identity.sha256 || '').toLowerCase();
+  return /^[a-f0-9]{64}$/.test(digest) ? digest : '';
+}
+
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }

package/src/tooling/portable/handoff/recipientV2.workspaceRepresentation.js

@@ -0,0 +1,163 @@
+import { sealC14nV2Self } from '../../../integrity/integrity.c14nV2.js';
+import { C14N_V2_VALIDATOR_TARGET } from '../../../integrity/integrity.methodReference.js';
+
+const RECIPIENT_V2_ROOT_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/tiinex.root.v1.schema.md';
+export const RECIPIENT_V2_WORKSPACE_REPRESENTATION_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/0fdce5f265298321a41cd90cf5382bcb6ae31a13/.topics/.schemas/relation/workspace/representation/tiinex.workspace.representation.v1.schema.md';
+
+const COMPLETE_CONTRACT = Object.freeze({
+  coverage: 'complete',
+  representationKind: 'exact-workspace-byte-tree-archive',
+  activationRule: 'verified-complete-only',
+  coverageRequirement: 'complete',
+  selectionRule: 'exactly-one-binding-per-workspace'
+});
+const BOUNDED_CONTRACT = Object.freeze({
+  coverage: 'bounded',
+  representationKind: 'exact-bounded-workspace-byte-tree-archive',
+  activationRule: 'verified-bounded-only',
+  coverageRequirement: 'bounded',
+  selectionRule: 'explicit-binding-per-bounded-scope'
+});
+
+export function renderRecipientV2WorkspaceRepresentation(input = {}) {
+  const createdAt = normalizeCreatedAt(input.createdAt || '');
+  const contract = String(input.coverage || 'complete') === 'bounded' ? BOUNDED_CONTRACT : COMPLETE_CONTRACT;
+  const scope = contract.coverage === 'bounded'
+    ? `\n## Representation Scope\n\n- Scope Basis: exact-representation-entry-set\n- Included Entry Authority: qualified-decoded-entry-set\n- Omitted Entry Meaning: outside-representation-not-absent-from-workspace\n- Source Membership Claim: represented-entries-are-workspace-relative-source-bytes\n- Recovery Closure Boundary: separate-qualified-closure\n`
+    : '';
+  const unsigned = `# Continuity Context\n\n- Envelope Schema: [tiinex.root.v1](${RECIPIENT_V2_ROOT_SCHEMA_TARGET})\n${renderParentEnvelope(input.parent)}- Current\n  - Current Schema: [tiinex.workspace.representation.v1](${RECIPIENT_V2_WORKSPACE_REPRESENTATION_SCHEMA_TARGET})\n  - Created At: ${createdAt}\n  - Summary: ${String(input.summary || 'Explicit canonical binding between one package-local Workspace artifact and one exact Workspace archive External Payload.')}\n\n---\n\n# ${String(input.title || 'Workspace Representation')}\n\n## Representation Binding\n\n- Workspace Artifact: [${String(input.workspaceLabel || 'Workspace artifact')}](${String(input.workspaceArtifactPath || '')})\n- Representation Payload: [${String(input.payloadLabel || 'Workspace representation payload')}](${String(input.payloadArtifactPath || '')})\n- Representation Kind: ${contract.representationKind}\n- Coverage: ${contract.coverage}\n- Binding State: ${String(input.bindingState || 'verified')}\n${scope}\n## Representation Correlation\n\n- Workspace Tree Root: ${String(input.workspaceTreeRoot || '.')}\n- Workspace Artifact Inner Path: ${String(input.workspaceArtifactInnerPath || '')}\n- Archive Entry Root: ${String(input.archiveEntryRoot || '.')}\n- Path Mapping: ${String(input.pathMapping || 'identity-relative-paths')}\n- Collision Policy: reject-ambiguous-or-unsafe-paths\n- Decoder Requirement: ${String(input.decoderRequirement || 'deterministic stored ZIP with safe-entry validation')}\n${input.mappingManifest ? `- Mapping Manifest: [Mapping Manifest](${String(input.mappingManifest)})\n` : ''}${input.entryIntegrityManifest ? `- Entry Integrity Manifest: [Entry Integrity Manifest](${String(input.entryIntegrityManifest)})\n` : ''}\n## Provider Qualification\n\n- Activation Rule: ${contract.activationRule}\n- Payload Integrity Requirement: verified-exact-payload-bytes\n- Coverage Requirement: ${contract.coverageRequirement}\n- Staleness Rule: requalify-on-binding-relevant-change\n- Selection Rule: ${contract.selectionRule}\n- Multi-Workspace Isolation: independent-binding-closure\n\n## Relation Boundary\n\n- Parent Boundary: neither endpoint becomes Parent through this representation relation\n- Workspace Identity Boundary: the referenced Workspace artifact remains the semantic Workspace identity\n- Payload Identity Boundary: the referenced External Payload owns archive identity and exact payload-byte integrity\n- Transport Boundary: package location, archive adjacency, repository transport, detached Parent/recovery closure, and decoder success are not binding authority\n- Outer Integrity Boundary: package-wide exact-file/tamper authority remains separately owned\n\n## Interpretation Limits\n\n- Does Not Prove: ${contract.coverage === 'bounded' ? 'whole-Workspace completeness, absence of omitted source paths, ' : ''}semantic correctness, provenance, authorship, acceptance, completion, source identity, permission, consent, or truth\n- Must Not Be Used As: ${contract.coverage === 'bounded' ? 'a complete Workspace snapshot, ' : ''}a replacement for Workspace identity, External Payload authority, Parent continuity, repository transport, preservation, Handoff state, or package-wide integrity authority\n\n## Evidence Basis\n\nProvider activation must requalify this visible binding, its explicit Workspace and External Payload endpoints, the exact payload bytes, decoder/mapping safety, bound Workspace inner entry, and ${contract.coverage === 'bounded' ? 'exact bounded representation entry set. Detached recovery closure is qualified separately and does not enter representation scope.' : 'complete archive entry set.'} Transport facts may detect tampering but are not semantic binding authority.\n\n---\n\n# Continuity Integrity\n\n${renderParentIntegrity(input.parent)}- [sha256-base64url-c14n-v2](${C14N_V2_VALIDATOR_TARGET})\n  - Towards: self\n  - Value: pending\n`;
+  return seal(unsigned);
+}
+
+export function parseRecipientV2WorkspaceRepresentation(markdown = '') {
+  const binding = sectionText(markdown, 'Representation Binding');
+  const scope = sectionText(markdown, 'Representation Scope');
+  const correlation = sectionText(markdown, 'Representation Correlation');
+  const qualification = sectionText(markdown, 'Provider Qualification');
+  return Object.freeze({
+    workspaceArtifactPath: markdownTarget(fieldValue(binding, 'Workspace Artifact')),
+    payloadArtifactPath: markdownTarget(fieldValue(binding, 'Representation Payload')),
+    representationKind: fieldValue(binding, 'Representation Kind'),
+    coverage: fieldValue(binding, 'Coverage'),
+    bindingState: fieldValue(binding, 'Binding State'),
+    scopeBasis: fieldValue(scope, 'Scope Basis'),
+    includedEntryAuthority: fieldValue(scope, 'Included Entry Authority'),
+    omittedEntryMeaning: fieldValue(scope, 'Omitted Entry Meaning'),
+    sourceMembershipClaim: fieldValue(scope, 'Source Membership Claim'),
+    recoveryClosureBoundary: fieldValue(scope, 'Recovery Closure Boundary'),
+    workspaceTreeRoot: fieldValue(correlation, 'Workspace Tree Root'),
+    workspaceArtifactInnerPath: fieldValue(correlation, 'Workspace Artifact Inner Path'),
+    archiveEntryRoot: fieldValue(correlation, 'Archive Entry Root'),
+    pathMapping: fieldValue(correlation, 'Path Mapping'),
+    collisionPolicy: fieldValue(correlation, 'Collision Policy'),
+    decoderRequirement: fieldValue(correlation, 'Decoder Requirement'),
+    mappingManifest: markdownTarget(fieldValue(correlation, 'Mapping Manifest')),
+    entryIntegrityManifest: markdownTarget(fieldValue(correlation, 'Entry Integrity Manifest')),
+    activationRule: fieldValue(qualification, 'Activation Rule'),
+    payloadIntegrityRequirement: fieldValue(qualification, 'Payload Integrity Requirement'),
+    coverageRequirement: fieldValue(qualification, 'Coverage Requirement'),
+    stalenessRule: fieldValue(qualification, 'Staleness Rule'),
+    selectionRule: fieldValue(qualification, 'Selection Rule'),
+    multiWorkspaceIsolation: fieldValue(qualification, 'Multi-Workspace Isolation')
+  });
+}
+
+export function parseRecipientV2ExternalPayload(markdown = '') {
+  const identity = sectionText(markdown, 'Payload Identity');
+  const location = sectionText(markdown, 'Payload Location');
+  const integrity = sectionText(markdown, 'Integrity Reference');
+  return Object.freeze({
+    payloadRole: fieldValue(identity, 'Payload Role'),
+    workspaceId: fieldValue(identity, 'Workspace Id'),
+    mediaType: fieldValue(identity, 'Media Type'),
+    format: fieldValue(identity, 'Format'),
+    bytes: Number(fieldValue(identity, 'Byte Size') || 0),
+    location: markdownTarget(fieldValue(location, 'Location')),
+    integrityStatus: fieldValue(integrity, 'Integrity Status'),
+    integrityMethod: fieldValue(integrity, 'Integrity Method'),
+    integrityValue: fieldValue(integrity, 'Integrity Value'),
+    integrityTarget: fieldValue(integrity, 'Integrity Target')
+  });
+}
+
+export function correlateWorkspaceRepresentationFacts(markdown, facts, findings, path) {
+  if (!facts || facts.factsFormat !== 'portable-recipient-v2' || Number(facts.factsVersion || 0) !== 1) return;
+  const visible = parseRecipientV2WorkspaceRepresentation(markdown);
+  const checks = [
+    ['workspaceArtifactPath', visible.workspaceArtifactPath],
+    ['payloadArtifactPath', visible.payloadArtifactPath],
+    ['sourceWorkspaceTargetInnerPath', visible.workspaceArtifactInnerPath],
+    ['coverage', visible.coverage]
+  ];
+  for (const [key, observed] of checks) if (facts[key] && String(facts[key]) !== String(observed || '')) findings.push(finding('error', `portable.handoff-v2-surface.workspace-representation.visible-${key}-mismatch`, 'Workspace Representation visible semantic field diverges from its transport tamper-check facts.', { path, field: key }));
+}
+
+export function inspectWorkspaceRepresentationShape(markdown, findings, path) {
+  const required = {
+    'Representation Binding': ['Workspace Artifact','Representation Payload','Representation Kind','Coverage','Binding State'],
+    'Representation Correlation': ['Workspace Tree Root','Workspace Artifact Inner Path','Archive Entry Root','Path Mapping','Collision Policy','Decoder Requirement'],
+    'Provider Qualification': ['Activation Rule','Payload Integrity Requirement','Coverage Requirement','Staleness Rule','Selection Rule','Multi-Workspace Isolation'],
+    'Relation Boundary': ['Parent Boundary','Workspace Identity Boundary','Payload Identity Boundary','Transport Boundary','Outer Integrity Boundary'],
+    'Interpretation Limits': ['Does Not Prove','Must Not Be Used As']
+  };
+  for (const [section, fields] of Object.entries(required)) {
+    const text = sectionText(markdown, section);
+    if (!text) { findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.section-missing', `Workspace Representation artifact is missing required section ${section}.`, { path, section })); continue; }
+    for (const field of fields) if (!fieldValue(text, field)) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.field-missing', `Workspace Representation artifact is missing required field ${field}.`, { path, section, field }));
+  }
+  const parsed = parseRecipientV2WorkspaceRepresentation(markdown);
+  const contract = parsed.coverage === 'bounded' ? BOUNDED_CONTRACT : COMPLETE_CONTRACT;
+  const fixed = {
+    representationKind: contract.representationKind,
+    workspaceTreeRoot: '.', archiveEntryRoot: '.', pathMapping: 'identity-relative-paths', collisionPolicy: 'reject-ambiguous-or-unsafe-paths',
+    activationRule: contract.activationRule, payloadIntegrityRequirement: 'verified-exact-payload-bytes', coverageRequirement: contract.coverageRequirement,
+    stalenessRule: 'requalify-on-binding-relevant-change', selectionRule: contract.selectionRule, multiWorkspaceIsolation: 'independent-binding-closure'
+  };
+  if (!['complete', 'bounded', 'partial', 'unknown'].includes(parsed.coverage)) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.coverage-invalid', 'Workspace Representation coverage is outside the canonical domain.', { path, observed: parsed.coverage }));
+  if (parsed.coverage === 'bounded') {
+    const scope = {
+      scopeBasis: 'exact-representation-entry-set',
+      includedEntryAuthority: 'qualified-decoded-entry-set',
+      omittedEntryMeaning: 'outside-representation-not-absent-from-workspace',
+      sourceMembershipClaim: 'represented-entries-are-workspace-relative-source-bytes',
+      recoveryClosureBoundary: 'separate-qualified-closure'
+    };
+    for (const [key, expected] of Object.entries(scope)) if (parsed[key] !== expected) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.scope-contract-mismatch', 'Bounded Workspace Representation is missing or diverges from the canonical exact-scope contract.', { path, field: key, expected, observed: parsed[key] }));
+  }
+  for (const [key, expected] of Object.entries(fixed)) if (parsed[key] && parsed[key] !== expected) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.contract-mismatch', 'Workspace Representation artifact diverges from the canonical ready-provider contract for its coverage.', { path, field: key, expected, observed: parsed[key], coverage: parsed.coverage }));
+  if (!parsed.workspaceArtifactPath || !parsed.payloadArtifactPath) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.endpoint-missing', 'Workspace Representation must expose both semantic endpoints.', { path }));
+  if (parsed.pathMapping === 'manifest' && !parsed.mappingManifest) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.mapping-manifest-missing', 'Manifest path mapping requires an explicit Mapping Manifest.', { path }));
+}
+
+function renderParentEnvelope(parent = null) {
+  if (!parent) return '';
+  const path = String(parent.path || '').trim();
+  const label = String(parent.label || path || 'Parent');
+  const schemaId = String(parent.schemaId || '').trim();
+  const schemaTarget = String(parent.schemaTarget || '').trim();
+  const createdAt = normalizeCreatedAt(parent.createdAt || '');
+  if (!path || !schemaId || !schemaTarget || !String(parent.selfDigest || '').trim()) throw new Error('portable.handoff-v2-surface.parent-authority-incomplete');
+  return `- Parent\n  - Parent Schema: [${schemaId}](${schemaTarget})\n  - Created At: ${createdAt}\n  - Trace: [${label}](${path})\n  - Origin:\n    - [relative](${path})\n`;
+}
+function renderParentIntegrity(parent = null) {
+  if (!parent) return '';
+  const path = String(parent.path || '').trim();
+  const label = String(parent.label || path || 'Parent');
+  const digest = String(parent.selfDigest || '').trim();
+  if (!path || !digest) throw new Error('portable.handoff-v2-surface.parent-integrity-incomplete');
+  return `- [sha256-base64url-c14n-v2](${C14N_V2_VALIDATOR_TARGET})\n  - Towards: [${label}](${path})\n  - Value: ${digest}\n\n`;
+}
+function markdownTarget(value = '') { return String(value || '').match(/\[[^\]]*\]\(([^)]+)\)/)?.[1] || String(value || '').trim(); }
+function sectionText(markdown = '', heading = '') {
+  const re = new RegExp(`^##\\s+${escapeRe(heading)}\\s*$`, 'mi');
+  const match = re.exec(String(markdown || ''));
+  if (!match) return '';
+  const rest = String(markdown || '').slice(match.index + match[0].length);
+  const next = /^##\s+/m.exec(rest);
+  return (next ? rest.slice(0, next.index) : rest).trim();
+}
+function fieldValue(section = '', name = '') { const m = String(section || '').match(new RegExp(`^\\s*-\\s+${escapeRe(name)}:\\s*(.+?)\\s*$`, 'mi')); return String(m?.[1] || '').trim(); }
+function seal(unsigned) { const result = sealC14nV2Self(unsigned); if (result.state !== 'sealed') throw new Error(`portable.handoff-v2-surface.integrity.seal-failed:${result.reason || result.state}`); return `${result.markdown}\n`; }
+function normalizeCreatedAt(value = '') { const text = String(value || '').trim(); if (!text) return '1970-01-01 00:00:00'; return text.replace('T', ' ').replace(/\.\d{3}Z$/, '').replace(/Z$/, '').slice(0, 19); }
+function escapeRe(value = '') { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }

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

@@ -0,0 +1,130 @@
+import { validateArtifact } from '../../../validation/validateArtifact.js';
+import { C14N_V2_METHOD_ID, canonicalC14nV2SelfState, verifyC14nV2TargetSelfDigest } from '../../../integrity/integrity.c14nV2.js';
+import { portableRuntimeValidationContractForSchema } from '../schema/qualifiedLocalRoot.runtime.js';
+
+export const HANDOFF_ROUTE_ARTIFACT_CONFORMANCE_SCHEMA_ID = 'tiinex.portable.handoff-route-artifact-conformance.v1';
+
+const QUALIFIED_CONTRACT_STATES = new Set(['valid', 'valid-with-preserved-unknowns']);
+
+export function qualifyTiinexRouteArtifact(input = {}) {
+  const markdown = String(input.markdown || '');
+  const expectedSchemaId = String(input.expectedSchemaId || '').trim();
+  const requireExactContract = input.requireExactContract !== false;
+  const runtimeProjection = portableRuntimeValidationContractForSchema(expectedSchemaId);
+  const validation = validateArtifact({ markdown, validationContractOverride: runtimeProjection.state === 'qualified' ? runtimeProjection.compiledContract : null });
+  const parsed = validation.parsed || {};
+  const findings = [];
+
+  if (!expectedSchemaId) findings.push(finding('error', 'portable.route-artifact.expected-schema.missing', 'Route artifact qualification requires an expected declared schema identifier.'));
+  else if (String(validation.schemaId || '') !== expectedSchemaId) findings.push(finding('error', 'portable.route-artifact.schema.mismatch', `Route artifact declares ${validation.schemaId || 'no Current Schema'} instead of required ${expectedSchemaId}.`, { expectedSchemaId, observedSchemaId: String(validation.schemaId || '') }));
+
+  for (const item of validation.findings || []) {
+    if (item.severity !== 'error') continue;
+    findings.push(finding('error', item.code || 'portable.route-artifact.validation.error', item.message || 'Declared Tiinex contract validation failed.', { source: item.source || '', qualification: item.qualification || '' }));
+  }
+
+  if (requireExactContract) {
+    if (!validation.contractValidation?.available) findings.push(finding('error', 'portable.route-artifact.contract.unavailable', `Exact registered contract validation is unavailable for ${expectedSchemaId || validation.schemaId || 'the declared schema'}.`));
+    else if (!QUALIFIED_CONTRACT_STATES.has(String(validation.contractValidation.state || ''))) {
+      findings.push(finding('error', 'portable.route-artifact.contract.unqualified', `Declared Tiinex contract did not qualify: ${validation.contractValidation.state || 'unknown'}.`, { contractState: String(validation.contractValidation.state || '') }));
+    }
+  }
+
+  const selfIntegrity = canonicalC14nV2SelfState(markdown);
+  if (selfIntegrity.state !== 'verified') findings.push(finding('error', 'portable.route-artifact.integrity.self.unverified', `Exact route artifact self integrity is not verified: ${selfIntegrity.reason || selfIntegrity.state}.`, { integrityState: selfIntegrity.state, reason: selfIntegrity.reason || '' }));
+
+  const parentQualification = qualifyParentContinuity({ parsed, markdown, resolveParent: input.resolveParent, parentMarkdown: input.parentMarkdown });
+  findings.push(...parentQualification.findings);
+
+  const status = findings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified';
+  return deepFreeze({
+    schema: HANDOFF_ROUTE_ARTIFACT_CONFORMANCE_SCHEMA_ID,
+    version: 1,
+    status,
+    expectedSchemaId,
+    observedSchemaId: String(validation.schemaId || ''),
+    contractState: validation.contractValidation?.available ? String(validation.contractValidation.state || 'unknown') : 'unavailable',
+    validationState: String(validation.validation?.state || 'unknown'),
+    selfIntegrity: projectSelfIntegrity(selfIntegrity),
+    parentContinuity: parentQualification.projection,
+    findings: Object.freeze(findings),
+    boundary: 'Exact-byte Tiinex route-artifact qualification. Registered schema/Root validation and independently recomputed continuity integrity are qualification requirements; stored footer equality, package placement, filename, and carrier projections cannot override a schema or integrity failure.'
+  });
+}
+
+export function qualifySelectedHandoffArtifact(input = {}) {
+  return qualifyTiinexRouteArtifact({ ...input, expectedSchemaId: 'tiinex.handoff.v1', requireExactContract: true });
+}
+
+function qualifyParentContinuity({ parsed = {}, resolveParent, parentMarkdown = '' } = {}) {
+  const findings = [];
+  const parent = parsed?.envelope?.parent || {};
+  const parentDeclared = Boolean(parent?.schema?.id || parent?.createdAt || parent?.trace || parent?.origin || parent?.originEntries?.length);
+  if (!parentDeclared) return Object.freeze({ projection: Object.freeze({ state: 'not-required', parentDeclared: false, targetEntry: null, targetResolution: null }), findings: Object.freeze([]) });
+
+  const targetEntries = (parsed?.integrity?.entries || []).filter((entry) => entry?.method === C14N_V2_METHOD_ID && entry?.towards && entry.towards !== 'self');
+  const authorityTargets = parentAuthorityTargets(parent);
+  const authorityMatches = targetEntries.filter((entry) => authorityTargets.includes(String(entry.towards || '')));
+  let targetEntry = null;
+  if (authorityMatches.length === 1) targetEntry = authorityMatches[0];
+  else if (!authorityMatches.length && targetEntries.length === 1) targetEntry = targetEntries[0];
+  else if (!targetEntries.length) findings.push(finding('error', 'portable.route-artifact.integrity.parent-target.missing', 'Parent-bearing route artifact is missing a c14n-v2 Parent-target integrity entry.'));
+  else findings.push(finding('error', 'portable.route-artifact.integrity.parent-target.ambiguous', 'Parent-bearing route artifact has no unique c14n-v2 Parent-target integrity entry.', { targetEntryCount: targetEntries.length, authorityMatchCount: authorityMatches.length }));
+
+  let targetResolution = null;
+  if (targetEntry) {
+    if (typeof resolveParent === 'function') {
+      try { targetResolution = resolveParent({ parsed, parent, targetEntry }) || null; }
+      catch (error) { targetResolution = Object.freeze({ state: 'error', reason: String(error?.message || error || 'parent-resolution-failed') }); }
+    } else if (parentMarkdown) {
+      targetResolution = Object.freeze({ state: 'qualified', markdown: String(parentMarkdown), basis: 'supplied-parent-markdown' });
+    }
+    if (!targetResolution || targetResolution.state !== 'qualified' || !targetResolution.markdown) {
+      findings.push(finding('error', 'portable.route-artifact.integrity.parent-target.unresolved', 'Parent-target integrity cannot be independently qualified because the exact Parent representation is unavailable or ambiguous.', { targetState: String(targetResolution?.state || 'unavailable'), reason: String(targetResolution?.reason || '') }));
+    } else {
+      const verification = verifyC14nV2TargetSelfDigest({ value: targetEntry.value, targetMarkdown: targetResolution.markdown });
+      targetResolution = Object.freeze({ ...targetResolution, verification });
+      if (verification.state !== 'verified') findings.push(finding('error', 'portable.route-artifact.integrity.parent-target.unverified', `Parent-target integrity is not verified against the exact Parent representation: ${verification.reason || verification.state}.`, { targetState: verification.state, reason: verification.reason || '' }));
+    }
+  }
+
+  return Object.freeze({
+    projection: deepFreeze({
+      state: findings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified',
+      parentDeclared: true,
+      parentSchemaId: String(parent?.schema?.id || ''),
+      trace: String(parent?.trace || ''),
+      authorityTargets: Object.freeze(authorityTargets),
+      targetEntry: targetEntry ? Object.freeze({ method: targetEntry.method, towards: targetEntry.towards, value: targetEntry.value }) : null,
+      targetResolution: targetResolution ? projectTargetResolution(targetResolution) : null
+    }),
+    findings: Object.freeze(findings)
+  });
+}
+
+function parentAuthorityTargets(parent = {}) {
+  const targets = [];
+  for (const entry of parent.originEntries || []) if (String(entry?.label || '').trim() === 'browse + git' && entry?.target) targets.push(String(entry.target));
+  if (parent.trace) targets.push(String(parent.trace));
+  return [...new Set(targets.filter(Boolean))];
+}
+
+function projectSelfIntegrity(state = {}) {
+  return Object.freeze({ state: String(state.state || 'unknown'), reason: String(state.reason || ''), declaredValue: String(state.declaredValue || ''), computedValue: String(state.computedValue || '') });
+}
+
+function projectTargetResolution(value = {}) {
+  return Object.freeze({
+    state: String(value.state || 'unknown'),
+    reason: String(value.reason || ''),
+    basis: String(value.basis || ''),
+    workspaceRelativePath: String(value.workspaceRelativePath || ''),
+    packagePath: String(value.packagePath || ''),
+    sha256: String(value.sha256 || ''),
+    verification: value.verification ? Object.freeze({ state: String(value.verification.state || ''), reason: String(value.verification.reason || ''), expectedValue: String(value.verification.expectedValue || ''), targetValue: String(value.verification.targetValue || ''), computedTargetValue: String(value.verification.computedTargetValue || '') }) : null
+  });
+}
+
+
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

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

@@ -0,0 +1,67 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+
+export const PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_PATH = 'tiinex.bootstrap/manifest.json';
+export const PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_SCHEMA_ID = 'tiinex.portable.tooling-bootstrap.manifest.v1';
+
+export function inspectPortableToolingBootstrap(bundle = {}) {
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const byPath = new Map(files.map((file) => [String(file.path || ''), file]));
+  const findings = [];
+  const manifestFile = byPath.get(PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_PATH);
+  const manifest = parseJsonFile(manifestFile);
+  if (!manifest) findings.push(finding('error', 'portable.tooling-bootstrap.manifest.missing', 'Portable Tooling bootstrap manifest is missing or unreadable.'));
+  else if (String(manifest.schema || '') !== PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_SCHEMA_ID) findings.push(finding('error', 'portable.tooling-bootstrap.manifest.schema', 'Portable Tooling bootstrap manifest schema is unsupported.', { actual: manifest.schema || '' }));
+
+  const delivery = String(manifest?.delivery || '');
+  const entrypoint = String(manifest?.entrypoint || '').trim();
+  if (manifest && !['embedded', 'persistent'].includes(delivery)) findings.push(finding('error', 'portable.tooling-bootstrap.delivery.unsupported', 'Portable Tooling bootstrap delivery mode is unsupported.', { delivery }));
+  if (manifest && !entrypoint) findings.push(finding('error', 'portable.tooling-bootstrap.entrypoint.missing', 'Portable Tooling bootstrap manifest must declare one exact runtime entrypoint.'));
+  else if (entrypoint && (!entrypoint.startsWith('runtime/') || entrypoint.includes('..'))) findings.push(finding('error', 'portable.tooling-bootstrap.entrypoint.invalid', 'Portable Tooling bootstrap entrypoint must be one normalized runtime-relative path.', { entrypoint }));
+  const declared = new Map();
+  for (const entry of manifest?.runtime?.entries || []) {
+    const relative = String(entry.path || '');
+    const packagePath = `tiinex.bootstrap/${relative}`;
+    if (!relative.startsWith('runtime/') || declared.has(packagePath)) {
+      findings.push(finding('error', 'portable.tooling-bootstrap.entry.invalid', 'Bootstrap runtime manifest contains an invalid or duplicate runtime entry.', { path: relative }));
+      continue;
+    }
+    declared.set(packagePath, entry);
+    if (delivery !== 'embedded') continue;
+    const file = byPath.get(packagePath);
+    if (!file) {
+      findings.push(finding('error', 'portable.tooling-bootstrap.runtime.missing', 'Embedded Tooling bootstrap runtime entry is missing from package bytes.', { path: packagePath }));
+      continue;
+    }
+    const data = packageFileBytes(file);
+    if (Number(entry.bytes || 0) !== data.byteLength) findings.push(finding('error', 'portable.tooling-bootstrap.runtime.bytes-mismatch', 'Embedded Tooling bootstrap runtime byte length differs from its manifest.', { path: packagePath }));
+    if (String(entry.sha256 || '') !== sha256Hex(data)) findings.push(finding('error', 'portable.tooling-bootstrap.runtime.sha256-mismatch', 'Embedded Tooling bootstrap runtime digest differs from its manifest.', { path: packagePath }));
+  }
+  const entrypointPackagePath = entrypoint ? `tiinex.bootstrap/${entrypoint}` : '';
+  if (entrypointPackagePath && !declared.has(entrypointPackagePath)) findings.push(finding('error', 'portable.tooling-bootstrap.entrypoint.unlisted', 'Portable Tooling bootstrap entrypoint is not present in the exact manifest-declared runtime representation.', { entrypoint }));
+  const runtimeFiles = files.filter((file) => String(file.path || '').startsWith('tiinex.bootstrap/runtime/'));
+  if (delivery === 'embedded') {
+    for (const file of runtimeFiles) if (!declared.has(String(file.path || ''))) findings.push(finding('error', 'portable.tooling-bootstrap.runtime.unlisted', 'A package byte is colocated under the bootstrap runtime prefix but is not granted bootstrap authority by the manifest.', { path: file.path || '' }));
+    if (runtimeFiles.length !== declared.size) findings.push(finding('error', 'portable.tooling-bootstrap.runtime.cardinality', 'Embedded Tooling bootstrap runtime cardinality differs from its manifest.', { declared: declared.size, supplied: runtimeFiles.length }));
+  } else if (delivery === 'persistent' && runtimeFiles.length) {
+    findings.push(finding('error', 'portable.tooling-bootstrap.persistent.embedded-bytes', 'Persistent Tooling bootstrap mode must not silently embed runtime bytes.', { supplied: runtimeFiles.length }));
+  }
+  const representation = manifest?.runtime?.entries || [];
+  const representationSha256 = sha256Text(stableJson(representation));
+  if (manifest && String(manifest.runtime?.representationSha256 || '') !== representationSha256) findings.push(finding('error', 'portable.tooling-bootstrap.runtime.representation-mismatch', 'Tooling bootstrap runtime representation digest differs from the declared manifest entries.'));
+  return Object.freeze({
+    schema: 'tiinex.portable.tooling-bootstrap.inspection.v1',
+    status: findings.some((item) => item.severity === 'error') ? 'invalid' : 'valid',
+    delivery: delivery || 'unknown',
+    manifest,
+    entrypoint: entrypoint ? Object.freeze({ path: entrypoint, packagePath: entrypointPackagePath, state: declared.has(entrypointPackagePath) ? 'qualified' : 'unqualified' }) : null,
+    counts: Object.freeze({ declaredRuntimeFiles: declared.size, suppliedRuntimeFiles: runtimeFiles.length, findings: findings.length, errors: findings.filter((item) => item.severity === 'error').length }),
+    qualification: Object.freeze({ exactManifestMembershipRequired: true, exactEntrypointManifestMembershipRequired: true, filenameOrColocationAuthority: false, ordinaryWorkspaceBytesAreBootstrapAuthority: false }),
+    findings: Object.freeze(findings)
+  });
+}
+
+function parseJsonFile(file) { if (!file) return null; try { return JSON.parse(new TextDecoder().decode(packageFileBytes(file))); } catch { return null; } }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function sha256Text(value = '') { const bytes = new TextEncoder().encode(String(value)); return sha256Hex(bytes); }
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }