@tiinex/core 0.1.1

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

@@ -0,0 +1,55 @@
+export function correlateExternalPayloadFacts(markdown, facts, findings, path) {
+  if (!facts || facts.factsFormat !== 'portable-recipient-v2' || Number(facts.factsVersion || 0) !== 1) return;
+  const identity = sectionText(markdown, 'Payload Identity');
+  const location = sectionText(markdown, 'Payload Location');
+  const integrity = sectionText(markdown, 'Integrity Reference');
+  const visiblePath = markdownTarget(fieldValue(location, 'Location'));
+  if (facts.archivePath && visiblePath !== String(facts.archivePath)) findings.push(finding('error', 'portable.handoff-v2-surface.payload.visible-location-mismatch', 'External Payload visible Location diverges from its sealed machine facts.', { path }));
+  if (facts.archiveSha256 && fieldValue(integrity, 'Integrity Value') !== String(facts.archiveSha256)) findings.push(finding('error', 'portable.handoff-v2-surface.payload.visible-integrity-mismatch', 'External Payload visible integrity value diverges from its sealed machine facts.', { path }));
+  if (facts.archiveBytes !== undefined && Number(fieldValue(identity, 'Byte Size') || -1) !== Number(facts.archiveBytes)) findings.push(finding('error', 'portable.handoff-v2-surface.payload.visible-bytes-mismatch', 'External Payload visible byte size diverges from its sealed machine facts.', { path }));
+}
+export function correlateRelationFacts(markdown, facts, findings, path) {
+  if (!facts || facts.factsFormat !== 'portable-recipient-v2' || Number(facts.factsVersion || 0) !== 1) return;
+  const target = sectionText(markdown, 'Relation Target');
+  if (facts.relationDirection === 'payload artifact -> represented artifact') {
+    if (facts.payloadArtifactPath && markdownTarget(fieldValue(target, 'Source')) !== String(facts.payloadArtifactPath)) findings.push(finding('error', 'portable.handoff-v2-surface.relation.visible-source-mismatch', 'Relation visible Source diverges from its derived compatibility facts.', { path }));
+    if (facts.workspaceArtifactInnerPath && markdownTarget(fieldValue(target, 'Target')) !== String(facts.workspaceArtifactInnerPath)) findings.push(finding('error', 'portable.handoff-v2-surface.relation.visible-target-mismatch', 'Relation visible Target diverges from its derived compatibility facts.', { path }));
+    return;
+  }
+  if (facts.workspaceArtifactPath && markdownTarget(fieldValue(target, 'Source')) !== String(facts.workspaceArtifactPath)) findings.push(finding('error', 'portable.handoff-v2-surface.relation.visible-source-mismatch', 'Relation visible Source diverges from its sealed machine facts.', { path }));
+  if (facts.payloadArtifactPath && markdownTarget(fieldValue(target, 'Target')) !== String(facts.payloadArtifactPath)) findings.push(finding('error', 'portable.handoff-v2-surface.relation.visible-target-mismatch', 'Relation visible Target diverges from its sealed machine facts.', { path }));
+}
+export function correlatePointerFacts(markdown, facts, findings, path) {
+  if (!facts || facts.factsFormat !== 'portable-recipient-v2' || Number(facts.factsVersion || 0) !== 1) return;
+  if (facts.role !== 'handoff-route' || !facts.archivePath) return;
+  const targets = [...sectionText(markdown, 'Destinations').matchAll(/\[[^\]]*\]\(([^)]+)\)/g)].map((match) => match[1]);
+  if (targets.length !== 1 || targets[0] !== String(facts.archivePath)) findings.push(finding('error', 'portable.handoff-v2-surface.pointer.visible-destination-mismatch', 'Route Pointer visible Destination diverges from its sealed machine facts.', { path }));
+}
+export function markdownTarget(value = '') { return String(value || '').match(/\[[^\]]*\]\(([^)]+)\)/)?.[1] || String(value || '').trim(); }
+export function inspectExternalPayloadShape(markdown, findings, path) {
+  for (const section of ['Payload Identity', 'Payload Location', 'Integrity Reference', 'Access Boundary', 'Interpretation Limits']) if (!sectionText(markdown, section)) findings.push(finding('error', 'portable.handoff-v2-surface.payload.section-missing', `External Payload artifact is missing required section ${section}.`, { path, section }));
+  const required = [['Payload Identity', 'Payload Label'], ['Payload Identity', 'Payload Kind'], ['Payload Location', 'Location'], ['Payload Location', 'Location Type'], ['Integrity Reference', 'Integrity Status'], ['Access Boundary', 'Access Boundary']];
+  for (const [section, field] of required) if (!fieldValue(sectionText(markdown, section), field)) findings.push(finding('error', 'portable.handoff-v2-surface.payload.field-missing', `External Payload artifact is missing required field ${field}.`, { path, section, field }));
+}
+export function inspectRelationShape(markdown, findings, path) {
+  for (const section of ['Relation Declaration', 'Relation Target', 'Relation Boundary']) if (!sectionText(markdown, section)) findings.push(finding('error', 'portable.handoff-v2-surface.relation.section-missing', `Relation artifact is missing required section ${section}.`, { path, section }));
+  for (const field of ['Relation Type', 'Relation Direction', 'Relation Scope']) if (!fieldValue(sectionText(markdown, 'Relation Declaration'), field)) findings.push(finding('error', 'portable.handoff-v2-surface.relation.field-missing', `Relation artifact is missing required field ${field}.`, { path, field }));
+}
+export function currentSchemaId(markdown = '') {
+  const match = String(markdown || '').match(/Current Schema:\s*(?:\[)?(tiinex\.[a-z0-9._-]+)(?:\])?/i);
+  return String(match?.[1] || '').toLowerCase();
+}
+export 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();
+}
+export function fieldValue(section = '', name = '') { const m = String(section || '').match(new RegExp(`^\\s*-\\s+${escapeRe(name)}:\\s*(.+?)\\s*$`, 'mi')); return String(m?.[1] || '').trim(); }
+export function unquoteCode(value = '') { const text = String(value || '').trim(); return text.startsWith('`') && text.endsWith('`') ? text.slice(1, -1) : text; }
+export function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+export function escapeRe(value = '') { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+export function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+export 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/recipientV2.artifacts.js

@@ -0,0 +1,174 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { sealC14nV2Self } from '../../../integrity/integrity.c14nV2.js';
+import { C14N_V2_VALIDATOR_TARGET } from '../../../integrity/integrity.methodReference.js';
+import { qualifyTiinexRouteArtifact } from './routeArtifactConformance.js';
+import {
+  correlateExternalPayloadFacts,
+  correlatePointerFacts,
+  correlateRelationFacts,
+  currentSchemaId,
+  decodeUtf8,
+  deepFreeze,
+  fieldValue,
+  finding,
+  inspectExternalPayloadShape,
+  inspectRelationShape,
+  markdownTarget,
+  sectionText,
+  unquoteCode
+} from './recipientV2.artifactInspection.js';
+import {
+  RECIPIENT_V2_WORKSPACE_REPRESENTATION_SCHEMA_TARGET,
+  correlateWorkspaceRepresentationFacts,
+  inspectWorkspaceRepresentationShape,
+  parseRecipientV2WorkspaceRepresentation,
+  parseRecipientV2ExternalPayload,
+  renderRecipientV2WorkspaceRepresentation
+} from './recipientV2.workspaceRepresentation.js';
+export {
+  RECIPIENT_V2_WORKSPACE_REPRESENTATION_SCHEMA_TARGET,
+  parseRecipientV2WorkspaceRepresentation,
+  parseRecipientV2ExternalPayload,
+  renderRecipientV2WorkspaceRepresentation
+};
+
+
+export const RECIPIENT_V2_ROOT_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/tiinex.root.v1.schema.md';
+export const RECIPIENT_V2_POINTER_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/core/pointer/tiinex.pointer.v1.schema.md';
+export const RECIPIENT_V2_EXTERNAL_PAYLOAD_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/external/payload/tiinex.external.payload.v1.schema.md';
+export const RECIPIENT_V2_RELATION_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/relation/tiinex.relation.v1.schema.md';
+export const RECIPIENT_V2_WORKSPACE_SCHEMA_TARGET = 'https://github.com/Tiinex/site/blob/17283cd2f0b9b0782a149a0cd113fb88a5a55ef3/src/schemas/workspace/tiinex.workspace.v1.schema.md';
+export const RECIPIENT_V2_FACTS_BEGIN = '<!-- TIINEX-RECIPIENT-V2-FACTS:BEGIN -->';
+export const RECIPIENT_V2_FACTS_END = '<!-- TIINEX-RECIPIENT-V2-FACTS:END -->';
+
+export function renderRecipientV2Pointer(input = {}) {
+  const role = String(input.role || 'navigation');
+  const artifactFirst = input.artifactFirst === true;
+  const createdAt = normalizeCreatedAt(input.createdAt || '');
+  const destinations = (input.destinations || []).map((item) => `- ${String(item.label || 'Destination')}: [${String(item.display || item.target || '')}](${String(item.target || '')})`).join('\n');
+  const currentRead = (input.currentRead || []).map((item) => `- ${String(item.label || '')}: ${String(item.value || '')}`).join('\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.pointer.v1](${RECIPIENT_V2_POINTER_SCHEMA_TARGET})\n  - Created At: ${createdAt}\n  - Summary: ${String(input.summary || 'Recipient-facing Handoff carrier navigation pointer.')}\n\n---\n\n# ${String(input.title || 'Handoff Carrier Pointer')}\n\n${String(input.prose || 'This pointer provides one bounded navigation surface.')}\n\n## Current Read\n\n- Carrier Role: ${role}\n${currentRead ? `${currentRead}\n` : ''}\n${artifactFirst ? 'Compatibility transport inventory may be derived from these qualified artifacts and exact payload bytes; it is not semantic authority.' : 'Transport topology and exact byte-map evidence is carried in the package transport manifest.'}\n\n## Destinations\n\n${destinations || '- none'}\n\n## Interpretation Notes\n\n${artifactFirst ? '- Destinations are navigation only; they do not create Parent, provenance, package membership, Handoff acceptance, transfer authority, or representation authority.\n- Numeric pathing, sibling placement, and package adjacency are presentation/container facts only.' : '- Numeric pathing is not generic Tiinex semantic authority. In this Handoff package, the generator deliberately projects the declared package-local Parent lineage into matching numeric pathing for readable random-access traversal.\n- Exact carried source artifact bytes and independently verified payload bytes retain their own authority; package-local lineage does not rewrite their historical provenance.'}\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 renderRecipientV2ExternalPayload(input = {}) {
+  const artifactFirst = input.artifactFirst === true;
+  const createdAt = normalizeCreatedAt(input.createdAt || '');
+  const materialBindings = renderPayloadMaterialBindings(input.materials || []);
+  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.external.payload.v1](${RECIPIENT_V2_EXTERNAL_PAYLOAD_SCHEMA_TARGET})\n  - Created At: ${createdAt}\n  - Summary: ${String(input.summary || 'Recipient-facing payload reference.')}\n\n---\n\n# ${String(input.title || 'Carrier Payload')}\n\n## Payload Identity\n\n- Payload Label: ${String(input.label || input.title || 'carrier payload')}\n- Payload Kind: ${String(input.kind || 'archive')}\n- Media Type: ${String(input.mediaType || 'application/zip')}\n- Format: ${String(input.format || 'deterministic stored ZIP')}\n- Byte Size: ${Number(input.bytes || 0)}\n- Payload Role: ${String(input.role || 'recipient-relative transport payload')}\n${input.workspaceId ? `- Workspace Id: ${String(input.workspaceId)}\n` : ''}\n## Payload Location\n\n- Location: [${String(input.location || '')}](${String(input.location || '')})\n- Location Type: local\n- Access Method: read exact package-local payload bytes after this artifact qualifies\n- Storage Boundary: recipient-relative Handoff carrier only\n\n## Integrity Reference\n\n- Integrity Status: verified\n- Integrity Method: sha256\n- Integrity Value: ${String(input.sha256 || '')}\n- Integrity Target: exact payload bytes as carried at the declared local Location\n- Validation Method: independent byte digest plus payload-format qualification\n${materialBindings ? `\n## Payload Material Bindings\n\n${materialBindings}\n` : ''}\n## Access Boundary\n\n- Access Boundary: recipient-local package read\n- Publicly Shareable: unknown\n- Retention Policy: disposable with this recipient-relative carrier unless separately preserved\n\n## Interpretation Limits\n\n${artifactFirst ? '- This artifact owns one explicitly located package-local payload and its exact payload-byte integrity. Package placement and adjacency do not create Parent or representation authority.\n- Payload integrity does not create Workspace identity, Handoff acceptance, completion, semantic truth, or remote provenance.' : '- This artifact owns one package-local payload node. Its Parent is package-local continuity; the ZIP companion cannot carry a Markdown envelope but participates in this node through this artifact.\n- Payload integrity does not create Workspace identity, Handoff acceptance, completion, semantic truth, or remote provenance.'}\n\n## Evidence Basis\n\n${artifactFirst ? 'Compatibility transport inventory may copy this visible payload metadata and mechanical byte identity, but cannot override this artifact or the exact payload bytes.' : 'Transport topology and exact byte-map evidence is carried in the package transport manifest.'}\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 renderRecipientV2Workspace(input = {}) {
+  const createdAt = normalizeCreatedAt(input.createdAt || '');
+  const workspaceId = String(input.workspaceId || input.title || 'workspace');
+  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.v1](${RECIPIENT_V2_WORKSPACE_SCHEMA_TARGET})\n  - Created At: ${createdAt}\n  - Summary: Package-local Workspace node for ${workspaceId}; its archive-backed provider authority is the explicit canonical Workspace Representation artifact while the durable source Workspace artifact remains unchanged inside the payload.\n\n---\n\n# ${String(input.title || workspaceId)}\n\nThis is the package-local Workspace lineage node for **${workspaceId}**. Its canonical archive-backed provider binding is [${String(input.representationPath || 'Workspace Representation')}](${String(input.representationPath || '')}). The exact durable Workspace source remains inside the bound representation payload at \`${String(input.sourceWorkspaceInnerPath || '')}\` and keeps its original bytes and provenance.\n\nTransport topology and exact byte-map evidence is carried in the package transport manifest.\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);
+}
+
+// Retained for backward inspection compatibility; the corrected recipient-v2 topology no longer emits a visible relation artifact.
+export function renderRecipientV2Relation(input = {}) {
+  const artifactFirst = input.artifactFirst === true;
+  const createdAt = normalizeCreatedAt(input.createdAt || '');
+  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.relation.v1](${RECIPIENT_V2_RELATION_SCHEMA_TARGET})\n  - Created At: ${createdAt}\n  - Summary: ${String(input.summary || 'Typed non-Parent carrier representation relation.')}\n\n---\n\n# ${String(input.title || 'Workspace Representation Relation')}\n\n## Relation Declaration\n\n- Relation Type: ${String(input.relationType || 'exact workspace archive representation')}\n- Relation Direction: ${String(input.direction || 'Workspace artifact -> archive representation payload')}\n- Relation Scope: ${String(input.scope || 'artifact-level recipient-relative package carriage representation')}\n\n## Relation Target\n\n- Source: [${String(input.sourceLabel || 'Relation source')}](${String(input.source || '')})\n${input.sourceWorkspaceId ? `- Source Workspace Id: ${String(input.sourceWorkspaceId)}\n` : ''}${input.sourceWorkspaceInnerPath ? `- Source Workspace Inner Path: \`${String(input.sourceWorkspaceInnerPath)}\`\n` : ''}- Target: [${String(input.targetLabel || 'Relation target')}](${String(input.target || '')})\n${input.targetWorkspaceId ? `- Target Workspace Id: ${String(input.targetWorkspaceId)}\n` : ''}${input.targetWorkspaceInnerPath ? `- Target Workspace Inner Path: \`${String(input.targetWorkspaceInnerPath)}\`\n` : ''}\n\n## Relation Boundary\n\n- The relation target is not Parent.\n\n## Evidence Basis\n\n${artifactFirst ? 'This relation is receiver-readable semantic meaning. Any compatibility transport projection is derived evidence only and cannot override the visible relation endpoints or scope.' : 'Transport topology and exact byte-map evidence is carried in the package transport manifest.'}\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 parseRecipientV2Relation(markdown = '') {
+  const declaration = sectionText(markdown, 'Relation Declaration');
+  const target = sectionText(markdown, 'Relation Target');
+  return Object.freeze({
+    relationType: fieldValue(declaration, 'Relation Type'),
+    direction: fieldValue(declaration, 'Relation Direction'),
+    scope: fieldValue(declaration, 'Relation Scope'),
+    source: markdownTarget(fieldValue(target, 'Source')),
+    sourceWorkspaceId: unquoteCode(fieldValue(target, 'Source Workspace Id')),
+    sourceWorkspaceInnerPath: unquoteCode(fieldValue(target, 'Source Workspace Inner Path')),
+    target: markdownTarget(fieldValue(target, 'Target')),
+    targetWorkspaceId: unquoteCode(fieldValue(target, 'Target Workspace Id')),
+    targetWorkspaceInnerPath: unquoteCode(fieldValue(target, 'Target Workspace Inner Path'))
+  });
+}
+
+export { parseRecipientV2Pointer } from './recipientV2.pointer.js';
+export function inspectRecipientV2Artifact(file = {}, options = {}) {
+  const markdown = decodeUtf8(packageFileBytes(file));
+  const schemaId = currentSchemaId(markdown);
+  const facts = options.facts || parseFacts(markdown);
+  const findings = [];
+  const requireExactContract = options.requireExactContract === true || schemaId === 'tiinex.relation.v1' || schemaId === 'tiinex.workspace.representation.v1';
+  let conformance = null;
+  if (!schemaId) findings.push(finding('error', 'portable.handoff-v2-surface.artifact.schema-missing', 'Recipient-facing Markdown carrier lacks a Current Schema declaration.', { path: file.path || '' }));
+  else {
+    try {
+      conformance = qualifyTiinexRouteArtifact({
+        markdown,
+        expectedSchemaId: schemaId,
+        requireExactContract,
+        resolveParent: options.resolveParent,
+        parentMarkdown: options.parentMarkdown
+      });
+    } catch (error) {
+      findings.push(finding('error', 'portable.handoff-v2-surface.artifact.conformance-error', 'Recipient-facing Tiinex artifact conformance could not be evaluated.', { path: file.path || '', detail: String(error?.message || error || '') }));
+    }
+  }
+  if (conformance && conformance.status !== 'qualified') findings.push(...(conformance.findings || []).map((item) => finding(item.severity || 'error', item.code || 'portable.handoff-v2-surface.artifact.unqualified', item.message || 'Recipient-facing artifact failed Tiinex conformance.', { path: file.path || '' })));
+  if (!markdown.startsWith(`# Continuity Context\n\n- Envelope Schema: [tiinex.root.v1](${RECIPIENT_V2_ROOT_SCHEMA_TARGET})\n`)) findings.push(finding('error', 'portable.handoff-v2-surface.artifact.root-reference-noncanonical', 'Generated recipient artifact does not begin with the maintained Root schema link.', { path: file.path || '' }));
+  if (!/\n---\n\n# Continuity Integrity\n/.test(markdown)) findings.push(finding('error', 'portable.handoff-v2-surface.artifact.footer-divider-missing', 'Generated recipient artifact is missing the canonical body/footer divider before Continuity Integrity.', { path: file.path || '' }));
+  if (schemaId === 'tiinex.external.payload.v1') { inspectExternalPayloadShape(markdown, findings, file.path || ''); correlateExternalPayloadFacts(markdown, facts, findings, file.path || ''); }
+  if (schemaId === 'tiinex.relation.v1') { inspectRelationShape(markdown, findings, file.path || ''); correlateRelationFacts(markdown, facts, findings, file.path || ''); }
+  if (schemaId === 'tiinex.workspace.representation.v1') { inspectWorkspaceRepresentationShape(markdown, findings, file.path || ''); correlateWorkspaceRepresentationFacts(markdown, facts, findings, file.path || ''); }
+  if (schemaId === 'tiinex.pointer.v1') correlatePointerFacts(markdown, facts, findings, file.path || '');
+  if (!facts) findings.push(finding('error', 'portable.handoff-v2-surface.artifact.facts-missing', 'Recipient-facing generated carrier artifact is missing its transport-owned machine facts record.', { path: file.path || '', schemaId }));
+  else if (facts.factsFormat !== 'portable-recipient-v2' || Number(facts.factsVersion || 0) !== 1) findings.push(finding('error', 'portable.handoff-v2-surface.artifact.facts-format-invalid', 'Recipient-facing generated carrier facts use an unsupported transport format.', { path: file.path || '', schemaId }));
+  return deepFreeze({ status: findings.some((item) => item.severity === 'error') ? 'invalid' : 'qualified', path: String(file.path || ''), markdown, schemaId, facts, conformance, sha256: sha256Hex(packageFileBytes(file)), findings: Object.freeze(findings) });
+}
+
+export function parseRecipientV2Facts(markdown = '') { return parseFacts(markdown); }
+
+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 renderPayloadMaterialBindings(materials = []) {
+  return [...materials].map((item) => {
+    const requirementId = String(item?.requirementId || '').trim();
+    const classification = String(item?.classification || '').trim();
+    const referenceTarget = String(item?.referenceTarget || '').trim();
+    const archiveEntry = String(item?.archiveEntry || '').trim();
+    if (!requirementId || !referenceTarget || !archiveEntry) return '';
+    return `- Requirement Id: ${requirementId}\n  - Classification: ${classification || 'detached-material'}\n  - Material Reference: ${referenceTarget}\n  - Archive Entry: ${archiveEntry}${item?.routeWorkspaceId ? `\n  - Route Workspace Id: ${String(item.routeWorkspaceId)}` : ''}${item?.routePath ? `\n  - Route Path: ${String(item.routePath)}` : ''}${item?.sourceRequirementId ? `\n  - Source Requirement Id: ${String(item.sourceRequirementId)}` : ''}${item?.originalPath ? `\n  - Original Path: ${String(item.originalPath)}` : ''}${item?.bytes !== undefined ? `\n  - Byte Size: ${Number(item.bytes || 0)}` : ''}${item?.sha256 ? `\n  - SHA256: ${String(item.sha256)}` : ''}`;
+  }).filter(Boolean).join('\n');
+}
+
+function parseFacts(markdown = '') {
+  const source = String(markdown || '');
+  const begin = source.indexOf(RECIPIENT_V2_FACTS_BEGIN);
+  const end = source.indexOf(RECIPIENT_V2_FACTS_END);
+  if (begin < 0 || end <= begin || source.indexOf(RECIPIENT_V2_FACTS_BEGIN, begin + RECIPIENT_V2_FACTS_BEGIN.length) >= 0) return null;
+  const bounded = source.slice(begin + RECIPIENT_V2_FACTS_BEGIN.length, end).trim();
+  const match = bounded.match(/^```json\s*\n([\s\S]*?)\n```$/);
+  if (!match) return null;
+  try { return JSON.parse(match[1]); } catch { return null; }
+}
+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 stablePrettyJson(value) { return JSON.stringify(sortJson(value), null, 2); }
+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])])); }

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

@@ -0,0 +1,24 @@
+export function recipientColdProjection(carrier = {}, readPath = '001-1-READ-BEFORE-PROCEEDING.trace.md') {
+  const routes = Object.freeze((carrier.routes || []).map((route) => Object.freeze({ id: String(route.id || ''), state: String(route.state || ''), workspaceId: String(route.workspaceId || ''), workspaceRelativeHandoffPath: String(route.workspaceRelativePath || ''), packagePath: String(route.packagePath || ''), sha256: String(route.sha256 || ''), from: String(route.parties?.from || ''), to: String(route.parties?.to || '') })));
+  const workspaces = Object.freeze((carrier.workspaces || []).map((workspace) => Object.freeze({ id: String(workspace.id || ''), title: String(workspace.title || workspace.id || ''), slug: String(workspace.slug || ''), qualification: String(workspace.qualification || '') })));
+  const qualified = routes.filter((route) => route.state === 'qualified');
+  const workspaceMode = String(carrier.mode || '') === 'workspace';
+  return deepFreeze({
+    schema: 'tiinex.portable.handoff-cold-consumer-projection.v1', version: 1,
+    status: carrier.status === 'ready' ? 'ready' : 'blocked',
+    controls: Object.freeze({ start: readPath, carrier: 'visible-qualified-artifacts', closure: 'visible-qualified-artifacts-plus-exact-payload-bytes', fileMap: 'not-exposed-in-v2', manifest: 'not-exposed-in-v2' }),
+    preferredPath: Object.freeze(workspaceMode
+      ? { ingressKind: 'pointerless-workspace-package', firstSemanticOperation: 'orient-handoff-package', groundingOperation: 'none', qualificationOperation: 'workspace-qualification-after-orientation', minimalHostBootstrapActions: 1, nativeFallback: 'explicit-and-justified-only', providerSpecificSemanticAuthority: false }
+      : { ingressKind: 'routed-handoff-package', firstSemanticOperation: 'orient-handoff-package', groundingOperation: 'ground-cold-consumer', qualificationOperation: 'qualify-cold-start', minimalHostBootstrapActions: 1, nativeFallback: 'explicit-and-justified-only', providerSpecificSemanticAuthority: false }),
+    workspaces, routes,
+    selection: Object.freeze({ policy: String(carrier.selection?.policy || ''), qualifiedRouteCount: qualified.length, implicitRouteId: workspaceMode ? '' : qualified.length === 1 ? qualified[0].id : '' }),
+    authority: Object.freeze({ semanticAuthority: 'none', packageTruthRequired: true, routeBindingAuthority: workspaceMode ? 'none' : 'qualified-visible-artifact-plus-exact-payload-byte-truth-only' })
+  });
+}
+
+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/recipientV2.delivery.js

@@ -0,0 +1,48 @@
+import { inspectRecipientFacingV2Topology } from './recipientV2.inspect.js';
+import { RECIPIENT_V2_FORMAT_ID, RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+import { buildRecipientV2TransportManifestFile } from './recipientV2.transportManifest.js';
+
+export function selectRecipientFacingV2Delivery(bundle = {}, selector = '') {
+  const inspection = inspectRecipientFacingV2Topology(bundle);
+  if (inspection.status !== 'valid') return blocked(bundle, 'recipient-v2-source-unqualified', inspection.findings || []);
+  const route = selectRoute(inspection.carrierProjection?.routes || [], selector);
+  if (!route) return blocked(bundle, 'recipient-v2-route-selection-unresolved', []);
+  const routeMeta = (inspection.routes || []).find((item) => item.workspaceId === route.workspaceId && item.workspaceRelativeHandoffPath === route.workspaceRelativePath);
+  const workspace = (inspection.workspaces || []).find((item) => item.workspaceId === route.workspaceId);
+  if (!routeMeta || !workspace || !inspection.rootArtifact?.path) return blocked(bundle, 'recipient-v2-route-workspace-unresolved', []);
+  const byPath = new Map((bundle.files || []).map((file) => [String(file.path || ''), file]));
+  const factsByPath = new Map((inspection.artifactFacts || []).map((item) => [String(item.path || ''), item.facts || null]));
+  const pointerFile = byPath.get(routeMeta.pointerPath);
+  const pointerFacts = pointerFile ? factsByPath.get(String(pointerFile.path || '')) : null;
+  if (!pointerFile || !pointerFacts) return blocked(bundle, 'recipient-v2-route-pointer-unresolved', []);
+
+  // Preserve the original package root and READ artifact bytes so descendant Parent-target seals remain valid.
+  // Selected delivery prunes material branches; it does not rewrite the package-local lineage root in place.
+  const paths = new Set([
+    inspection.rootArtifact.path,
+    RECIPIENT_V2_READ_PATH,
+    routeMeta.pointerPath,
+    workspace.workspaceArtifactPath,
+    workspace.workspaceRepresentationArtifactPath,
+    workspace.workspacePayloadArtifactPath,
+    workspace.workspaceArchivePath
+  ].filter(Boolean));
+  addPayloadRole(bundle, paths, factsByPath, (facts) => !facts.workspaceId && !Array.isArray(facts.materials) && facts.entryCount !== undefined);
+  if (pointerFacts.cacheArtifactPath) addPayloadArtifact(bundle, paths, factsByPath, String(pointerFacts.cacheArtifactPath));
+  const selectedMaterialFiles = [...paths].map((path) => byPath.get(path)).filter(Boolean).map((file) => {
+    const facts = factsByPath.get(String(file.path || ''));
+    return facts ? Object.freeze({ ...file, transportFacts: facts }) : file;
+  }).sort((a, b) => String(a.path || '').localeCompare(String(b.path || '')));
+  const manifest = buildRecipientV2TransportManifestFile(selectedMaterialFiles, { format: RECIPIENT_V2_FORMAT_ID, packageRootPath: inspection.rootArtifact.path, entryArtifactPath: RECIPIENT_V2_READ_PATH });
+  const files = Object.freeze([...selectedMaterialFiles, manifest].sort((a, b) => String(a.path || '').localeCompare(String(b.path || ''))));
+  const selectedBundle = Object.freeze({ ...bundle, files, transportFormat: RECIPIENT_V2_FORMAT_ID, boundary: `${bundle.boundary || ''} Selected recipient-relative v2 delivery preserves the sealed package root/READ lineage and carries exactly one qualified material route branch.` });
+  const selectedInspection = inspectRecipientFacingV2Topology(selectedBundle);
+  const siblingRoutes = (selectedInspection.carrierProjection?.routes || []).filter((item) => item.state === 'qualified');
+  const status = selectedInspection.status === 'valid' && siblingRoutes.length === 1 && siblingRoutes[0].id === route.id ? 'ready' : 'blocked';
+  return Object.freeze({ schema: 'tiinex.portable.recipient-facing-handoff-v2.delivery.v1', status, routeId: route.id, bundle: selectedBundle, inspection: selectedInspection, findings: selectedInspection.findings || Object.freeze([]) });
+}
+
+function addPayloadRole(bundle, paths, factsByPath, predicate) { for (const file of bundle.files || []) { const facts = factsByPath.get(String(file.path || '')); if (!facts || !predicate(facts)) continue; paths.add(String(file.path || '')); if (facts.archivePath) paths.add(String(facts.archivePath)); } }
+function addPayloadArtifact(bundle, paths, factsByPath, artifactPath) { const file = (bundle.files || []).find((item) => String(item.path || '') === artifactPath); const facts = file ? factsByPath.get(String(file.path || '')) : null; if (!file || !facts) return; paths.add(artifactPath); if (facts.archivePath) paths.add(String(facts.archivePath)); }
+function selectRoute(routes, selector) { if (selector && typeof selector === 'object') return routes.find((route) => route.id === selector.id && route.workspaceId === selector.workspaceId && route.workspaceRelativePath === selector.workspaceRelativePath) || null; const value = String(selector || ''); return routes.find((route) => route.id === value || route.workspaceRelativePath === value) || (routes.length === 1 ? routes[0] : null); }
+function blocked(bundle, reason, findings) { return Object.freeze({ schema: 'tiinex.portable.recipient-facing-handoff-v2.delivery.v1', status: 'blocked', routeId: '', bundle, inspection: null, findings: Object.freeze([...(findings || []), Object.freeze({ severity: 'error', code: `portable.handoff-v2-delivery.${reason}`, message: 'Recipient-facing v2 selected delivery could not be qualified.' })]) }); }

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

@@ -0,0 +1,179 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { RECIPIENT_V2_POINTER_SCHEMA_TARGET, renderRecipientV2Pointer } from './recipientV2.artifacts.js';
+import { recipientV2TransportFacts } from './recipientV2.transportManifest.js';
+
+export function buildEndpointRolePointerChain(input = {}) {
+  const files = [];
+  const roles = [];
+  const findings = [];
+  let lineageParent = input.lineageParent || null;
+  let nextDimension = String(input.nextDimension || '');
+  for (const requirement of input.requirements || []) {
+    const target = input.resolveRoleMaterialTarget(requirement, input.descriptor, input.workspaceById, input.cache, input.route);
+    if (target.state !== 'qualified') {
+      findings.push(finding('error', `portable.handoff-v2-surface.endpoint-role.${target.reason || 'unresolved'}`, 'Endpoint Role requirement did not resolve to one exact carried Workspace/cache representation.', { routeId: String(input.route?.id || ''), requirementId: String(requirement.id || '') }));
+      continue;
+    }
+    const party = String(requirement.party || requirement.fields?.Side || '').toLowerCase() || 'endpoint';
+    const roleToken = safeToken(requirement.roleLabel || requirement.name || target.referenceTarget || `${party}-role`);
+    const rolePointerPath = `${nextDimension}-${party}-${roleToken}-endpoint-role-pointer.trace.md`;
+    const roleFacts = {
+      workspaceId: input.workspace.workspaceId,
+      routeId: String(input.route?.id || ''),
+      endpointRequirementId: String(requirement.id || ''),
+      endpointParty: party,
+      roleLabelHint: String(requirement.roleLabel || ''),
+      referenceTarget: String(target.referenceTarget || ''),
+      targetCarrierKind: target.carrierKind,
+      targetWorkspaceId: String(target.targetWorkspaceId || ''),
+      archivePath: target.archivePath,
+      archiveSha256: target.archiveSha256,
+      targetInnerPath: String(target.innerPath || ''),
+      targetArchiveEntry: String(target.archiveEntry || ''),
+      targetBytes: Number(target.bytes || 0),
+      targetSha256: String(target.sha256 || '')
+    };
+    const rolePointer = finalizeFile({
+      path: rolePointerPath,
+      kind: 'endpoint-role-pointer',
+      logicalKind: 'recipient-v2-endpoint-role-pointer',
+      mediaType: 'text/markdown',
+      transportFacts: recipientV2TransportFacts('endpoint-role', roleFacts),
+      content: renderRecipientV2Pointer({
+        createdAt: input.createdAt,
+        parent: lineageParent,
+        role: 'endpoint-role',
+        title: `Endpoint Role Pointer — ${String(requirement.roleLabel || requirement.name || 'Role')}`,
+        summary: 'Package-local Pointer to one exact Handoff endpoint Role artifact for the selected Handoff route.',
+        prose: 'This Pointer grounds one exact Handoff From/To Role endpoint in an explicit carried Workspace/cache representation. It does not prove a human holder, consent, Handoff acceptance, or Role authority beyond the referenced Role artifact.',
+        currentRead: [
+          { label: 'Route Id', value: `\`${String(input.route?.id || '')}\`` },
+          { label: 'Endpoint Requirement Id', value: `\`${String(requirement.id || '')}\`` },
+          { label: 'Endpoint Party', value: party },
+          ...(roleFacts.roleLabelHint ? [{ label: 'Role Label Hint', value: roleFacts.roleLabelHint }] : []),
+          { label: 'Role Reference', value: roleFacts.referenceTarget ? `\`${roleFacts.referenceTarget}\`` : 'exact carried target' },
+          { label: 'Target Carrier Kind', value: target.carrierKind },
+          { label: 'Target Payload', value: `[payload](${target.archivePath})` },
+          ...(target.carrierKind === 'workspace-archive-entry'
+            ? [{ label: 'Target Workspace Id', value: `\`${String(target.targetWorkspaceId || '')}\`` }, { label: 'Target Inner Path', value: `\`${String(target.innerPath || '')}\`` }]
+            : []),
+          ...(target.carrierKind === 'workspace-cache-entry'
+            ? [{ label: 'Target Archive Entry', value: `\`${String(target.archiveEntry || '')}\`` }]
+            : [])
+        ],
+        destinations: [{ label: 'Exact endpoint Role carrier', display: `${target.archivePath} :: ${target.innerPath || target.archiveEntry}`, target: target.archivePath }],
+        facts: roleFacts
+      })
+    });
+    files.push(rolePointer);
+    roles.push(Object.freeze({
+      pointerPath: rolePointerPath,
+      workspaceId: input.workspace.workspaceId,
+      routeId: String(input.route?.id || ''),
+      requirementId: String(requirement.id || ''),
+      endpointParty: party,
+      roleLabelHint: String(requirement.roleLabel || ''),
+      referenceTarget: String(target.referenceTarget || ''),
+      targetCarrierKind: target.carrierKind,
+      targetWorkspaceId: String(target.targetWorkspaceId || ''),
+      targetInnerPath: String(target.innerPath || target.archiveEntry || ''),
+      targetSha256: String(target.sha256 || '')
+    }));
+    lineageParent = input.parentAuthority(rolePointer, 'tiinex.pointer.v1', RECIPIENT_V2_POINTER_SCHEMA_TARGET, input.createdAt);
+    nextDimension = `${nextDimension}-1`;
+  }
+  return Object.freeze({
+    files: Object.freeze(files),
+    roles: Object.freeze(roles),
+    findings: Object.freeze(findings),
+    lineageParent,
+    nextDimension
+  });
+}
+
+
+export function buildParticipantRolePointerChain(input = {}) {
+  const files = [];
+  const roles = [];
+  const findings = [];
+  let lineageParent = input.lineageParent || null;
+  let nextDimension = String(input.nextDimension || '');
+  for (const requirement of input.requirements || []) {
+    const target = input.resolveRoleMaterialTarget(requirement, input.descriptor, input.workspaceById, input.cache, input.route);
+    if (target.state !== 'qualified') {
+      findings.push(finding('error', `portable.handoff-v2-surface.participant-role.${target.reason || 'unresolved'}`, 'Role grounding requirement did not resolve to one exact carried Workspace/cache representation.', { routeId: String(input.route?.id || ''), requirementId: String(requirement.id || '') }));
+      continue;
+    }
+    const roleToken = safeToken(requirement.roleLabel || requirement.name || target.referenceTarget || 'participant-role');
+    const rolePointerPath = `${nextDimension}-${roleToken}-role-pointer.trace.md`;
+    const roleFacts = {
+      workspaceId: input.workspace.workspaceId,
+      routeId: String(input.route?.id || ''),
+      participantRequirementId: String(requirement.id || ''),
+      roleLabelHint: String(requirement.roleLabel || ''),
+      referenceTarget: String(target.referenceTarget || ''),
+      targetCarrierKind: target.carrierKind,
+      targetWorkspaceId: String(target.targetWorkspaceId || ''),
+      archivePath: target.archivePath,
+      archiveSha256: target.archiveSha256,
+      targetInnerPath: String(target.innerPath || ''),
+      targetArchiveEntry: String(target.archiveEntry || ''),
+      targetBytes: Number(target.bytes || 0),
+      targetSha256: String(target.sha256 || '')
+    };
+    const rolePointer = finalizeFile({
+      path: rolePointerPath,
+      kind: 'participant-role-pointer',
+      logicalKind: 'recipient-v2-participant-role-pointer',
+      mediaType: 'text/markdown',
+      transportFacts: recipientV2TransportFacts('participant-role', roleFacts),
+      content: renderRecipientV2Pointer({
+        createdAt: input.createdAt,
+        parent: lineageParent,
+        role: 'participant-role',
+        title: `Role Grounding Pointer — ${String(requirement.roleLabel || requirement.name || 'Role')}`,
+        summary: 'Package-local Pointer to one exact Role artifact required for recipient grounding before the selected Handoff route.',
+        prose: 'This Pointer is recipient discovery/grounding only. It does not declare semantic participation, change Handoff From/To, prove a human holder, or create Role authority; participation meaning remains owned by authoritative Handoff/Relation/context authority.',
+        currentRead: [
+          { label: 'Route Id', value: `\`${String(input.route?.id || '')}\`` },
+          { label: 'Grounding Requirement Id', value: `\`${String(requirement.id || '')}\`` },
+          ...(roleFacts.roleLabelHint ? [{ label: 'Role Label Hint', value: roleFacts.roleLabelHint }] : []),
+          { label: 'Role Reference', value: roleFacts.referenceTarget ? `\`${roleFacts.referenceTarget}\`` : 'exact carried target' },
+          { label: 'Target Carrier Kind', value: target.carrierKind },
+          { label: 'Target Payload', value: `[payload](${target.archivePath})` },
+          ...(target.carrierKind === 'workspace-archive-entry'
+            ? [{ label: 'Target Workspace Id', value: `\`${String(target.targetWorkspaceId || '')}\`` }, { label: 'Target Inner Path', value: `\`${String(target.innerPath || '')}\`` }]
+            : []),
+          ...(target.carrierKind === 'workspace-cache-entry'
+            ? [{ label: 'Target Archive Entry', value: `\`${String(target.archiveEntry || '')}\`` }]
+            : [])
+        ],
+        destinations: [{ label: 'Exact Role grounding carrier', display: `${target.archivePath} :: ${target.innerPath || target.archiveEntry}`, target: target.archivePath }],
+        facts: roleFacts
+      })
+    });
+    files.push(rolePointer);
+    roles.push(Object.freeze({
+      pointerPath: rolePointerPath,
+      workspaceId: input.workspace.workspaceId,
+      routeId: String(input.route?.id || ''),
+      requirementId: String(requirement.id || ''),
+      targetCarrierKind: target.carrierKind,
+      targetWorkspaceId: String(target.targetWorkspaceId || ''),
+      targetInnerPath: String(target.innerPath || target.archiveEntry || ''),
+      targetSha256: String(target.sha256 || '')
+    }));
+    lineageParent = input.parentAuthority(rolePointer, 'tiinex.pointer.v1', RECIPIENT_V2_POINTER_SCHEMA_TARGET, input.createdAt);
+    nextDimension = `${nextDimension}-1`;
+  }
+  return Object.freeze({
+    files: Object.freeze(files),
+    roles: Object.freeze(roles),
+    findings: Object.freeze(findings),
+    lineageParent,
+    nextDimension
+  });
+}
+
+function safeToken(value = '') { return String(value || '').trim().toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'workspace'; }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }

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

@@ -0,0 +1,28 @@
+export const RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY = 'outer-invocation-exact-package-local-handoff-route-pointer';
+export const RECIPIENT_V2_SIBLING_ROUTE_INFERENCE = false;
+
+export function recipientV2EntryCurrentRead() {
+  return Object.freeze([
+    Object.freeze({ label: 'Bootstrap Exception', value: 'before Tiinex Tooling is available, use host capabilities only to read this entry/bootstrap node and extract the declared bootstrap ZIP into a writable runtime location; do not unpack Workspace/cache payloads or perform package archaeology' }),
+    Object.freeze({ label: 'Tooling Entrypoint', value: '`runtime/tools/tiinex-portable.mjs` relative to the chosen bootstrap extraction root; use this exact path and do not search/list the extracted runtime to discover it' }),
+    Object.freeze({ label: 'First Tooling Invocation', value: '`node <bootstrap-root>/runtime/tools/tiinex-portable.mjs orient-handoff-package <untouched-handoff-package.zip>`' }),
+    Object.freeze({ label: 'Continue From', value: 'do not read the outer Continue-from Pointer natively; keep that exact package-local path opaque until Tooling takeover' }),
+    Object.freeze({ label: 'Grounding', value: 'after orientation, run `node <bootstrap-root>/runtime/tools/tiinex-portable.mjs ground <untouched-handoff-package.zip> --route <Continue-from>`; this is the shared human/LLM decision-grounding path and returns bounded authority, exact Required Context pointers, selected-route Parent leaf, compact cold-start continuity-to-root proof, current-work frontier, blockers, and exact recovery guidance. Accepted pinned repository Parents may resolve only deterministic relative Parents in the same repository/ref context; repeated host recovery remains explicit through `accept-host-receipt --prior <previous-accepted.json>` and the same `ground --recovery <newest-accepted.json>` path' }),
+    Object.freeze({ label: 'Cold-start Qualification', value: '`qualify-cold-start <untouched-handoff-package.zip> --route <Continue-from> --pre-takeover ...` is only for qualifying or measuring the cold-start process itself; it is not a second normal grounding path' }),
+    Object.freeze({ label: 'Route Selection', value: 'the outer invocation must name exactly one package-local Handoff Route Pointer from this package; never infer among sibling Handoff routes' }),
+    Object.freeze({ label: 'Fallback', value: 'fail closed when Tooling cannot qualify the selected route or its declared dependency/integrity evidence; native package archaeology is not a preferred-path substitute' })
+  ]);
+}
+
+
+export function recipientV2WorkspaceEntryCurrentRead() {
+  return Object.freeze([
+    Object.freeze({ label: 'Bootstrap Exception', value: 'before Tiinex Tooling is available, use host capabilities only to read this entry/bootstrap node and extract the declared bootstrap ZIP into a writable runtime location; do not unpack Workspace payloads or perform package archaeology' }),
+    Object.freeze({ label: 'Tooling Entrypoint', value: '`runtime/tools/tiinex-portable.mjs` relative to the chosen bootstrap extraction root; use this exact path and do not search/list the extracted runtime to discover it' }),
+    Object.freeze({ label: 'First Tooling Invocation', value: '`node <bootstrap-root>/runtime/tools/tiinex-portable.mjs orient-handoff-package <untouched-workspace-package.zip>`' }),
+    Object.freeze({ label: 'Carrier Mode', value: 'pointerless Workspace carrier; no Handoff route, Continue-from Pointer, endpoint Role, current work, transfer, acceptance, completion, or participation is declared or inferred' }),
+    Object.freeze({ label: 'Route Selection', value: 'none; the canonical package role requires Route Placement Rule, Continue-From Rule, and Pre-Handoff Closure Rule to all be exactly `none`' }),
+    Object.freeze({ label: 'Next Action', value: 'after Tooling orientation, use only the qualified carried Workspace identities and exact Workspace landing/inspection operations required by the consuming workflow' }),
+    Object.freeze({ label: 'Fallback', value: 'fail closed when Tooling cannot qualify the package role, exact Workspace bindings, bootstrap, or all-none Route Discovery profile; native package archaeology is not a preferred-path substitute' })
+  ]);
+}

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

@@ -0,0 +1,78 @@
+import { projectHandoffCarrierOutputFromPackage, projectHandoffHumanOutput } from './carrierProjection.js';
+import { inspectRecipientFacingV2Topology } from './recipientV2.inspect.js';
+import { RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+
+export function recipientV2StandardInvocation(humanOutput = {}, inspection = {}) {
+  const route = humanOutput.selectedRoute || {};
+  return recipientV2InvocationForRoute(route, inspection);
+}
+
+function recipientV2InvocationForRoute(route = {}, inspection = {}) {
+  const routeMeta = (inspection.routes || []).find((item) => String(item.workspaceId || '') === String(route.workspaceId || '') && String(item.workspaceRelativeHandoffPath || '') === String(route.workspaceRelativePath || ''));
+  if (!routeMeta?.pointerPath || !route.workspaceRelativePath || !route.workspaceId) return '';
+  return [
+    'Handoff package attached.',
+    '',
+    'Cold start: read Start directly; do not list or extract this package.',
+    '',
+    'Start:',
+    RECIPIENT_V2_READ_PATH,
+    'Continue from (do not read native; pass to Tiinex after bootstrap):',
+    String(routeMeta.pointerPath),
+    ''
+  ].join('\n');
+}
+
+export function projectRecipientV2HumanOutput(humanOutput = {}, inspection = {}) {
+  if (humanOutput.status !== 'ready' && humanOutput.status !== 'selection-required') return humanOutput;
+  const invocation = humanOutput.primary ? recipientV2StandardInvocation(humanOutput, inspection) : '';
+  if (humanOutput.primary && !invocation) return Object.freeze({ ...humanOutput, status: 'blocked', findings: Object.freeze([...(humanOutput.findings || []), Object.freeze({ severity: 'error', code: 'portable.handoff-v2-human-output.route-pointer.unresolved', message: 'Recipient-v2 human output requires one exact package-local Handoff route pointer for the selected semantic Handoff.' })]) });
+  const sharedRoutes = (humanOutput.sharedRouting?.routes || []).map((item) => {
+    const route = (inspection.carrierProjection?.routes || []).find((candidate) => String(candidate.id || '') === String(item.routeId || ''))
+      || { id: item.routeId, workspaceId: item.workspaceId, workspaceRelativePath: item.workspaceRelativeHandoffPath };
+    const transportText = recipientV2InvocationForRoute(route, inspection);
+    return transportText ? Object.freeze({ ...item, transportText }) : null;
+  });
+  if (humanOutput.sharedRouting && sharedRoutes.some((item) => !item)) return Object.freeze({ ...humanOutput, status: 'blocked', findings: Object.freeze([...(humanOutput.findings || []), Object.freeze({ severity: 'error', code: 'portable.handoff-v2-human-output.shared-route-pointer.unresolved', message: 'Recipient-v2 shared human output requires one exact package-local Handoff route pointer for every qualified route.' })]) });
+  const sharedRouting = humanOutput.sharedRouting ? Object.freeze({ ...humanOutput.sharedRouting, routes: Object.freeze(sharedRoutes) }) : null;
+  return Object.freeze({
+    ...humanOutput,
+    normalInlineRouting: humanOutput.normalInlineRouting ? Object.freeze({ ...humanOutput.normalInlineRouting, content: invocation }) : null,
+    sharedRouting,
+    fallbackTransportText: humanOutput.fallbackTransportText ? Object.freeze({ ...humanOutput.fallbackTransportText, content: invocation }) : null,
+    boundary: `${String(humanOutput.boundary || '')} Recipient-v2 host-layer routing is a deterministic address label only: the fixed package Start artifact and exact package-local Continue-from Handoff Route Pointers. Workspace, semantic Handoff path, Role, and Task stay package-owned; shared route texts are read-only addresses and sibling routes remain unselected until one exact qualified route is chosen.`
+  });
+}
+
+export function projectPortableHandoffCarrierOutputFromPackage(input = {}) {
+  const bundle = input.bundle || input;
+  const inspection = inspectRecipientFacingV2Topology(bundle);
+  if (inspection.detected !== true) return projectHandoffCarrierOutputFromPackage(input);
+  const humanOutput = projectRecipientV2HumanOutput(projectHandoffHumanOutput({ projection: inspection.carrierProjection || {}, route: input.route || input.routePath || input.routeId || '', collisionInstance: input.collisionInstance || input.instance || 1 }), inspection);
+  const findings = Object.freeze([...(inspection.findings || []), ...(humanOutput.findings || [])]);
+  const status = inspection.status === 'valid' && humanOutput.status === 'ready' ? 'ready' : humanOutput.status === 'selection-required' ? 'selection-required' : 'blocked';
+  const carrierInspection = boundedRecipientV2Inspection(inspection);
+  return deepFreeze({ schema: 'tiinex.portable.handoff-carrier-output-projection.v1', status, carrierInspection, humanOutput, findings, boundary: 'Read-only regeneration of recipient-v2 carrier filename and minimal Start/Continue-from transport address from package-qualified route truth. Package byte/provider internals are intentionally omitted from the human-output projection.' });
+}
+
+
+function boundedRecipientV2Inspection(inspection = {}) {
+  return Object.freeze({
+    schema: String(inspection.schema || ''),
+    status: String(inspection.status || 'invalid'),
+    format: String(inspection.format || ''),
+    rootArtifact: inspection.rootArtifact ? Object.freeze({ ...inspection.rootArtifact }) : null,
+    entrypoint: inspection.readArtifact ? Object.freeze({ path: String(inspection.readArtifact.path || ''), status: String(inspection.readArtifact.status || '') }) : null,
+    workspaces: Object.freeze((inspection.workspaces || []).map((item) => Object.freeze({ workspaceId: String(item.workspaceId || ''), workspaceArtifactPath: String(item.workspaceArtifactPath || ''), workspaceArchivePath: String(item.workspaceArchivePath || '') }))),
+    routes: Object.freeze((inspection.routes || []).map((item) => Object.freeze({ pointerPath: String(item.pointerPath || ''), workspaceId: String(item.workspaceId || ''), workspaceRelativeHandoffPath: String(item.workspaceRelativeHandoffPath || '') }))),
+    findingSummary: Object.freeze({ ...(inspection.findingSummary || {}) }),
+    findings: Object.freeze([...(inspection.findings || [])])
+  });
+}
+
+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);
+}