@tiinex/core 0.1.1

package/src/tooling/portable/handoff/materialClosure.requirements.js

@@ -0,0 +1,137 @@
+import { parseNamedDeclarationSection } from '../schema/named.declarations.js';
+
+export const PORTABLE_HANDOFF_MATERIAL_REQUIREMENTS_SCHEMA_ID = 'tiinex.portable.handoff-material-requirements.v1';
+
+export function projectHandoffMaterialRequirements(handoff = {}) {
+  const markdown = String(handoff.markdown || handoff.content || handoff.text || '');
+  const findings = [];
+  const required = projectSection(markdown, '## Required Context', 'required', findings);
+  const reference = projectSection(markdown, '## Reference Context', 'reference', findings);
+  const endpointRoles = projectEndpointRoleRequirements(markdown, findings);
+  return deepFreeze({
+    schema: PORTABLE_HANDOFF_MATERIAL_REQUIREMENTS_SCHEMA_ID,
+    handoff: Object.freeze({
+      id: String(handoff.id || handoff.path || ''),
+      path: String(handoff.path || ''),
+      reference: String(handoff.reference || handoff.permalink || ''),
+      semanticStatus: String(handoff.semanticStatus || handoff.validation?.status || 'unknown')
+    }),
+    required,
+    reference,
+    endpointRoles,
+    dependencies: Object.freeze([]),
+    counts: Object.freeze({ required: required.length, reference: reference.length, endpointRoles: endpointRoles.length, dependencies: 0 }),
+    findings: Object.freeze(findings)
+  });
+}
+
+export function projectParticipantRoleRequirements(participantRoles = [], scope = {}) {
+  const routeWorkspaceId = String(scope.workspaceId || '').trim();
+  const routePath = String(scope.routePath || scope.path || '').trim();
+  const routeToken = safeToken(`${routeWorkspaceId}-${routePath}`);
+  return Object.freeze((participantRoles || []).map((entry, index) => {
+    const role = typeof entry === 'string' ? { reference: entry } : (entry || {});
+    const targetWorkspaceId = String(role.workspaceId || role.targetWorkspaceId || '').trim();
+    const targetPath = String(role.path || role.targetPath || '').trim();
+    const rawReference = String(role.reference || role.referenceTarget || targetPath || '').trim();
+    const reference = parseMaterialReference(rawReference);
+    return Object.freeze({
+      id: `participant-role:${routeToken}:${index + 1}`,
+      name: String(role.label || role.roleLabel || `participant-role-${index + 1}`),
+      classification: 'participant-role',
+      roleLabel: String(role.label || role.roleLabel || ''),
+      material: 'Role artifact required for package-local recipient grounding',
+      purpose: 'package-local pre-Handoff Role grounding only; does not declare semantic participation',
+      availability: 'declared',
+      materialReference: rawReference,
+      reference,
+      routeWorkspaceId,
+      routePath,
+      targetWorkspaceId,
+      targetPath,
+      source: null,
+      fields: Object.freeze({ RouteWorkspace: routeWorkspaceId, RoutePath: routePath, TargetWorkspace: targetWorkspaceId, TargetPath: targetPath, Reference: rawReference })
+    });
+  }));
+}
+
+function projectSection(markdown, heading, classification, findings) {
+  const parsed = parseNamedDeclarationSection(markdown, heading);
+  findings.push(...(parsed.findings || []).map((item) => finding('warning', `portable.handoff-material.${classification}.parse.${item.code || 'finding'}`, 'Handoff context declaration parsing reported a structural finding.', { classification, ...item })));
+  const out = [];
+  for (const entry of parsed.entries || []) {
+    if (String(entry.name || '').trim().toLowerCase() === 'none') continue;
+    const fields = entry.fields || {};
+    const rawReference = String(fields['Material Reference'] || '').trim();
+    const reference = parseMaterialReference(rawReference);
+    out.push(Object.freeze({
+      id: `${classification}:${safeToken(entry.name)}`,
+      name: String(entry.name || ''),
+      classification,
+      material: String(fields.Material || ''),
+      purpose: String(fields.Purpose || ''),
+      availability: String(fields.Availability || 'unknown'),
+      materialReference: rawReference,
+      reference,
+      source: entry.source || null,
+      fields: Object.freeze({ ...fields })
+    }));
+  }
+  return Object.freeze(out);
+}
+
+
+function projectEndpointRoleRequirements(markdown, findings) {
+  const section = sectionText(markdown, 'Handoff Parties');
+  if (!section) return Object.freeze([]);
+  const out = [];
+  for (const side of ['From', 'To']) {
+    const kind = field(section, `${side} Kind`).toLowerCase();
+    const rawReference = field(section, `${side} Reference`);
+    if (kind !== 'role' || !rawReference) continue;
+    const reference = parseMaterialReference(rawReference);
+    if (!reference.exactTargetDeclared) findings.push(finding('warning', 'portable.handoff-material.endpoint-role.reference-opaque', 'Role endpoint declares a Reference that is not an exact Markdown-link target.', { side: side.toLowerCase(), reference: rawReference }));
+    out.push(Object.freeze({
+      id: `endpoint-role:${side.toLowerCase()}`,
+      name: field(section, side) || `${side} Role`,
+      classification: 'endpoint-role',
+      party: side.toLowerCase(),
+      roleLabel: field(section, side),
+      roleKind: kind,
+      material: `${side} endpoint Role artifact`,
+      purpose: 'cold-start endpoint Role grounding',
+      availability: 'declared',
+      materialReference: rawReference,
+      reference,
+      source: null,
+      fields: Object.freeze({ Side: side, Role: field(section, side), Kind: kind, Reference: rawReference })
+    }));
+  }
+  return Object.freeze(out);
+}
+
+function sectionText(markdown = '', heading = '') {
+  const match = new RegExp(`^##\\s+${escapeRe(heading)}\\s*$`, 'mi').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 field(section = '', name = '') {
+  const match = String(section || '').match(new RegExp(`^\\s*-\\s+${escapeRe(name)}:\\s*(.+?)\\s*$`, 'mi'));
+  return String(match?.[1] || '').trim();
+}
+function escapeRe(value = '') { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+export function parseMaterialReference(value = '') {
+  const raw = String(value || '').trim();
+  const link = raw.match(/^\[([^\]\r\n]+)\]\(([^)\s]+)\)$/);
+  if (link) return Object.freeze({ form: 'markdown-link', raw, label: link[1], target: link[2], exactTargetDeclared: true });
+  return Object.freeze({ form: raw ? 'opaque' : 'absent', raw, label: '', target: raw, exactTargetDeclared: false });
+}
+
+function safeToken(value = '') {
+  return String(value || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || 'material';
+}
+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; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

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

@@ -0,0 +1,105 @@
+import path from 'node:path';
+import { projectQualifiedHandoffEndpoints } from './handoffEndpointProjection.js';
+import { projectQualifiedHandoffLeaves } from './handoffLeafProjection.js';
+import { projectQualifiedWorkspacePackageSources } from './workspacePackageSources.js';
+
+export const PORTABLE_OPERATOR_CONTEXT_SCHEMA_ID = 'tiinex.portable.operator-context.v1';
+
+export function projectPortableOperatorContext(input = {}) {
+  const files = Array.isArray(input.files) ? input.files : [];
+  const repositories = normalizeRepositories(input.repositories || input.localRepositories || []);
+  const roots = normalizeRoots(input.workspaceRoots || input.roots || [], repositories);
+  const findings = [];
+  const projectedRoots = [];
+  const flattenedWorkspaces = [];
+  const flattenedLeaves = [];
+  const flattenedEndpoints = [];
+
+  if (!roots.length) {
+    findings.push(finding('error', 'portable.operator-context.roots.required', 'Operator context requires explicit Workspace roots; repository basenames or ambient process paths are not semantic Workspace identity.'));
+  }
+
+  for (const root of roots) {
+    const rootFiles = files.filter((file) => fileBelongsToRoot(file, root.root));
+    const rootRepositories = repositories.filter((repository) => samePath(repository.root, root.root));
+    const sources = projectQualifiedWorkspacePackageSources({ files: rootFiles, repositories: rootRepositories.length ? rootRepositories : repositories });
+    const workspaces = [];
+    for (const candidate of sources.candidates || []) {
+      const leaves = projectQualifiedHandoffLeaves({ files: rootFiles });
+      const endpoints = projectQualifiedHandoffEndpoints({ files: rootFiles, workspaceId: candidate.workspaceId });
+      const workspace = freeze({
+        ...candidate,
+        hostRootId: root.id,
+        hostRoot: root.root,
+        handoffLeaves: leaves.leaves || [],
+        pointerless: leaves.pointerless,
+        endpoints: endpoints.candidates || []
+      });
+      workspaces.push(workspace);
+      flattenedWorkspaces.push(workspace);
+      for (const leaf of workspace.handoffLeaves) flattenedLeaves.push(freeze({ ...leaf, workspaceId: candidate.workspaceId, hostRootId: root.id, hostRoot: root.root }));
+      for (const endpoint of workspace.endpoints) flattenedEndpoints.push(freeze({ ...endpoint, hostRootId: root.id, hostRoot: root.root }));
+    }
+    findings.push(...(sources.findings || []).map((item) => finding(item.severity || 'warning', item.code || 'portable.operator-context.workspace-source', item.message || 'Workspace source projection finding.', { ...(item.context || {}), hostRootId: root.id, hostRoot: root.root })));
+    projectedRoots.push(freeze({ id: root.id, root: root.root, repository: rootRepositories[0] || null, workspaces }));
+  }
+
+  const workspaceIds = new Map();
+  for (const workspace of flattenedWorkspaces) workspaceIds.set(workspace.workspaceId, (workspaceIds.get(workspace.workspaceId) || 0) + 1);
+  for (const [workspaceId, count] of workspaceIds.entries()) {
+    if (count > 1) findings.push(finding('error', 'portable.operator-context.workspace-id.ambiguous', 'Multiple explicit roots projected the same package-local Workspace identity; the host must not collapse them by repository basename.', { workspaceId, count }));
+  }
+
+  const status = findings.some((item) => item.severity === 'error') ? 'blocked' : 'ready';
+  const pointerless = freeze({
+    selectionLabel: 'No Handoff pointer',
+    packageRole: 'recipient-facing-workspace-carrier',
+    semanticState: 'qualified-canonical-docs',
+    manufactureState: status === 'ready' ? 'ready' : 'blocked',
+    blockerCode: status === 'ready' ? '' : 'portable.operator-context.blocked',
+    consequence: 'Workspace transport only — no Handoff semantics.'
+  });
+  return freeze({
+    schema: PORTABLE_OPERATOR_CONTEXT_SCHEMA_ID,
+    status,
+    roots: projectedRoots,
+    workspaces: flattenedWorkspaces.sort((a, b) => a.workspaceId.localeCompare(b.workspaceId) || a.workspaceTargetPath.localeCompare(b.workspaceTargetPath)),
+    handoffLeaves: flattenedLeaves.sort((a, b) => a.workspaceId.localeCompare(b.workspaceId) || a.path.localeCompare(b.path)),
+    endpoints: dedupeEndpoints(flattenedEndpoints),
+    pointerless,
+    findings,
+    operationBoundary: { sourceMutation: false, remoteWrite: false, manufacture: false, identityInference: false },
+    boundary: 'Projects one multi-root operator context from explicit host roots. Qualified Workspace artifact identity remains distinct from physical repository identity; Role/Party endpoints and Handoff leaves are shared-core projections, and No Handoff pointer remains explicit.'
+  });
+}
+
+function normalizeRoots(value = [], repositories = []) {
+  const supplied = Array.isArray(value) ? value : [];
+  const list = supplied.length ? supplied : repositories.map((repository) => ({ id: repository.id || repository.root, root: repository.root }));
+  const seen = new Set();
+  const roots = [];
+  for (const item of list) {
+    const root = path.resolve(String(item?.root || item?.path || '')).replace(/\\/g, '/').replace(/\/$/, '');
+    if (!root || seen.has(root)) continue;
+    seen.add(root);
+    roots.push(freeze({ id: String(item?.id || root), root }));
+  }
+  return roots;
+}
+function normalizeRepositories(value = []) {
+  return (Array.isArray(value) ? value : []).map((item) => freeze({ ...item, id: String(item?.id || item?.root || ''), root: path.resolve(String(item?.root || item?.id || '')).replace(/\\/g, '/').replace(/\/$/, '') })).filter((item) => item.root);
+}
+function fileBelongsToRoot(file = {}, root = '') {
+  const localPath = String(file?.locator?.localPath || '').replace(/\\/g, '/');
+  if (!localPath || !root) return false;
+  const base = String(root).replace(/\\/g, '/').replace(/\/$/, '');
+  return localPath === base || localPath.startsWith(`${base}/`);
+}
+function samePath(a = '', b = '') { return String(a || '').replace(/\\/g, '/').replace(/\/$/, '') === String(b || '').replace(/\\/g, '/').replace(/\/$/, ''); }
+function dedupeEndpoints(candidates = []) {
+  const byTarget = new Map();
+  for (const candidate of candidates) byTarget.set(candidate.target, candidate);
+  return [...byTarget.values()].sort((a, b) => a.kind.localeCompare(b.kind) || a.label.localeCompare(b.label) || a.target.localeCompare(b.target));
+}
+function finding(severity, code, message, context = {}) { return freeze({ severity, code, message, context }); }
+function freeze(value) { if (Array.isArray(value)) return Object.freeze(value.map(freeze)); if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freeze(item)]))); }

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

@@ -0,0 +1,138 @@
+import { packageFileBytes, sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+import { canonicalC14nV2SelfState, sealC14nV2Self } from '../../../integrity/integrity.c14nV2.js';
+import { C14N_V2_VALIDATOR_TARGET } from '../../../integrity/integrity.methodReference.js';
+import { inspectHandoffCarrierProjection } from './carrierProjection.js';
+import { qualifyTiinexRouteArtifact } from './routeArtifactConformance.js';
+
+export const HANDOFF_POINTER_ENTRYPOINT_PROJECTION_SCHEMA_ID = 'tiinex.portable.handoff-pointer-entrypoints.v1';
+export const HANDOFF_POINTER_ENTRYPOINT_INSPECTION_SCHEMA_ID = 'tiinex.portable.handoff-pointer-entrypoints.inspection.v1';
+export const HANDOFF_POINTER_ENTRYPOINT_PREFIX = 'handoff-entrypoint-';
+export const CANONICAL_POINTER_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/core/pointer/tiinex.pointer.v1.schema.md';
+
+const BOUNDARY = 'Generated package-root tiinex.pointer.v1 orientation only. Pointer filename, prose, and placement have no Parent, assignment, acceptance, completion, source, package-identity, or route-selection authority; qualified package carrier/closure truth remains controlling.';
+
+export function buildHandoffPointerEntrypoints(input = {}) {
+  const carrier = input.carrierProjection || input.projection || {};
+  const createdAt = normalizeCreatedAt(input.createdAt || '');
+  const qualifiedRoutes = carrier.status === 'ready' ? (carrier.routes || []).filter((route) => route.state === 'qualified') : [];
+  const entries = qualifiedRoutes.map((route) => buildPointerEntry(route, createdAt));
+  return deepFreeze({
+    schema: HANDOFF_POINTER_ENTRYPOINT_PROJECTION_SCHEMA_ID,
+    version: 1,
+    status: carrier.status === 'ready' && entries.length === qualifiedRoutes.length && entries.length > 0 ? 'ready' : 'blocked',
+    boundary: BOUNDARY,
+    canonicalPointerSchema: CANONICAL_POINTER_SCHEMA_TARGET,
+    entries: Object.freeze(entries),
+    authority: Object.freeze({ semanticAuthority: 'none', routeSelectionAuthority: 'package-qualified-route-membership-only', parentAuthority: false, sourceAuthority: false })
+  });
+}
+
+export function inspectHandoffPointerEntrypoints(bundle = {}, options = {}) {
+  const findings = [];
+  const carrierInspection = options.carrierInspection || inspectHandoffCarrierProjection(bundle);
+  if (carrierInspection.status !== 'valid') findings.push(finding('error', 'portable.handoff-pointer.carrier.invalid', 'Handoff Pointer entrypoints cannot qualify because package carrier truth is invalid.'));
+  const carrier = carrierInspection.projection || {};
+  const createdAt = packageCreatedAt(bundle);
+  const expected = buildHandoffPointerEntrypoints({ carrierProjection: carrier, createdAt });
+  const actualFiles = (bundle.files || []).filter((file) => isHandoffPointerEntrypointPath(file.path));
+  const actualByPath = new Map();
+  for (const file of actualFiles) {
+    const path = String(file.path || '');
+    const list = actualByPath.get(path) || [];
+    list.push(file);
+    actualByPath.set(path, list);
+  }
+  for (const [path, files] of actualByPath) if (files.length > 1) findings.push(finding('error', 'portable.handoff-pointer.duplicate-path', 'Multiple generated Pointer carriers use the same package-root path.', { path, count: files.length }));
+
+  const expectedByPath = new Map((expected.entries || []).map((entry) => [entry.path, entry]));
+  const qualifiedTargets = new Set((carrier.routes || []).filter((route) => route.state === 'qualified').map((route) => String(route.pointerTarget || route.packagePath || '')));
+  const actualEntries = [];
+  for (const file of actualFiles) {
+    const parsed = parsePointer(file);
+    actualEntries.push(parsed);
+    if (parsed.schemaState !== 'qualified') findings.push(finding('error', 'portable.handoff-pointer.schema.invalid', 'Package-root Pointer is not an ordinary tiinex.pointer.v1 artifact.', { path: parsed.path }));
+    if (parsed.integrityState !== 'verified') findings.push(finding('error', 'portable.handoff-pointer.integrity.invalid', 'Package-root Pointer self integrity is not verified.', { path: parsed.path, integrityState: parsed.integrityState }));
+    if (parsed.conformance.status !== 'qualified') findings.push(finding('error', 'portable.handoff-pointer.conformance.invalid', 'Generated package-root Pointer fails Tiinex Root/continuity conformance.', { path: parsed.path, reasons: parsed.conformance.findings.map((item) => item.code) }));
+    if (parsed.targets.length !== 1) findings.push(finding('error', 'portable.handoff-pointer.target.cardinality', 'Each package route Pointer must expose exactly one explicit destination.', { path: parsed.path, count: parsed.targets.length }));
+    if (/^\s*-\s+Parent\b/m.test(parsed.markdown)) findings.push(finding('error', 'portable.handoff-pointer.parent.promotion', 'Generated package route Pointer must not mint Parent continuity. ', { path: parsed.path }));
+    for (const target of parsed.targets) if (!qualifiedTargets.has(target)) findings.push(finding('error', 'portable.handoff-pointer.target.unqualified-route', 'Pointer target is not a package-qualified Handoff route.', { path: parsed.path, target }));
+    const expectedEntry = expectedByPath.get(parsed.path);
+    if (!expectedEntry) findings.push(finding('error', 'portable.handoff-pointer.unexpected', 'Package contains an unexpected route Pointer projection.', { path: parsed.path }));
+    else if (parsed.markdown !== expectedEntry.markdown) findings.push(finding('error', 'portable.handoff-pointer.projection.mismatch', 'Pointer bytes diverge from the projection independently rebuilt from package route truth.', { path: parsed.path }));
+  }
+  for (const expectedEntry of expected.entries || []) if (!actualByPath.has(expectedEntry.path)) findings.push(finding('error', 'portable.handoff-pointer.missing', 'Package is missing the expected route-specific root Pointer.', { path: expectedEntry.path, routeId: expectedEntry.routeId }));
+  if (actualFiles.length !== (expected.entries || []).length) findings.push(finding('error', 'portable.handoff-pointer.count.mismatch', 'Package-root Pointer count diverges from qualified route count.', { actual: actualFiles.length, expected: (expected.entries || []).length }));
+
+  return deepFreeze({
+    schema: HANDOFF_POINTER_ENTRYPOINT_INSPECTION_SCHEMA_ID,
+    status: findings.some((item) => item.severity === 'error') ? 'invalid' : 'valid',
+    projection: expected,
+    entries: Object.freeze(actualEntries.map(({ markdown, ...entry }) => Object.freeze(entry))),
+    carrierInspection,
+    findings: Object.freeze(findings),
+    findingSummary: Object.freeze({ findings: findings.length, errors: findings.filter((item) => item.severity === 'error').length }),
+    boundary: BOUNDARY
+  });
+}
+
+export function isHandoffPointerEntrypointPath(value = '') {
+  const path = String(value || '');
+  return path.startsWith(HANDOFF_POINTER_ENTRYPOINT_PREFIX) && path.endsWith('.trace.md') && !path.includes('/');
+}
+
+function buildPointerEntry(route = {}, createdAt = '') {
+  const path = pointerPath(route);
+  const title = `Handoff route pointer — ${String(route.parties?.to || route.workspaceId || 'recipient')}`;
+  const unsigned = `# Continuity Context\n\n- Envelope Schema: tiinex.root.v1\n- Current\n  - Current Schema: [tiinex.pointer.v1](${CANONICAL_POINTER_SCHEMA_TARGET})\n  - Created At: ${createdAt}\n  - Summary: Thin package-local pointer to one qualified Handoff route.\n\n---\n\n# ${title}\n\nThis generated pointer exposes one next hop only. Package carrier and closure controls remain the authority for whether that Handoff route is qualified.\n\n## Destinations\n\n- Qualified Handoff route: [${route.workspaceRelativePath}](${route.pointerTarget || route.packagePath})\n\n# Continuity Integrity\n\n- [sha256-base64url-c14n-v2](${C14N_V2_VALIDATOR_TARGET})\n  - Towards: self\n  - Value: \n`;
+  const sealed = sealC14nV2Self(unsigned);
+  if (sealed.state !== 'sealed') throw new Error(`portable.handoff-pointer.integrity.seal-failed:${sealed.reason || sealed.state}`);
+  return deepFreeze({
+    path,
+    routeId: String(route.id || ''),
+    workspaceId: String(route.workspaceId || ''),
+    targetPackagePath: String(route.pointerTarget || route.packagePath || ''),
+    targetSha256: String(route.sha256 || ''),
+    markdown: `${sealed.markdown}\n`,
+    boundary: BOUNDARY
+  });
+}
+
+function pointerPath(route = {}) {
+  const seed = String(route.id || `${route.workspaceId}:${route.workspaceRelativePath}`);
+  const token = slug(`${route.workspaceId}-${route.dimension || ''}-${route.parties?.to || ''}`) || 'route';
+  return `${HANDOFF_POINTER_ENTRYPOINT_PREFIX}${token}-${sha256Hex(utf8Bytes(seed)).slice(0, 12)}.trace.md`;
+}
+
+function parsePointer(file = {}) {
+  const markdown = decodeUtf8(packageFileBytes(file));
+  const schemaState = /Current Schema:\s*\[tiinex\.pointer\.v1\]\([^)]+\)/i.test(markdown) || /Current Schema:\s*tiinex\.pointer\.v1\b/i.test(markdown) ? 'qualified' : 'invalid';
+  const integrityState = canonicalC14nV2SelfState(markdown).state;
+  const targets = parseDestinationTargets(markdown);
+  const conformance = qualifyTiinexRouteArtifact({ markdown, expectedSchemaId: 'tiinex.pointer.v1', requireExactContract: false });
+  return Object.freeze({ path: String(file.path || ''), schemaState, integrityState, conformance, targets: Object.freeze(targets), sha256: sha256Hex(packageFileBytes(file)), markdown });
+}
+
+function parseDestinationTargets(markdown = '') {
+  const source = String(markdown || '');
+  const heading = /^##\s+Destinations\s*$/mi.exec(source);
+  if (!heading) return [];
+  const afterHeading = source.slice(heading.index + heading[0].length);
+  const nextHeading = /^#{1,2}\s+/m.exec(afterHeading);
+  const section = nextHeading ? afterHeading.slice(0, nextHeading.index) : afterHeading;
+  const out = [];
+  const link = /\[[^\]\r\n]+\]\(([^)\r\n]+)\)/g;
+  let found;
+  while ((found = link.exec(section))) out.push(String(found[1] || '').trim());
+  return out;
+}
+
+function packageCreatedAt(bundle = {}) {
+  const manifest = parseJsonFile((bundle.files || []).find((file) => String(file.path || '') === 'tiinex.package/manifest.json')) || bundle.manifest || {};
+  return normalizeCreatedAt(manifest.createdAt || bundle.builtAt || '');
+}
+function normalizeCreatedAt(value = '') { return String(value || '').trim() || '1970-01-01T00:00:00.000Z'; }
+function parseJsonFile(file = null) { try { return file ? JSON.parse(decodeUtf8(packageFileBytes(file))) : null; } catch { return null; } }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function slug(value = '') { return String(value || '').trim().toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 96); }
+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/qualifiedHandoffFixture.js

@@ -0,0 +1,34 @@
+import { sealC14nV2Self } from '../../../integrity/integrity.c14nV2.js';
+import { C14N_V2_VALIDATOR_TARGET } from '../../../integrity/integrity.methodReference.js';
+
+const ROOT_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/tiinex.root.v1.schema.md';
+const HANDOFF_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/coordination/handoff/tiinex.handoff.v1.schema.md';
+const TASK_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/053d46ce082d4ec261b82abc44ecca403d61e240/.topics/.schemas/core/task/tiinex.task.v1.schema.md';
+
+export function qualifiedHandoffFixture(input = {}) {
+  const title = String(input.title || `Qualified ${input.to || 'recipient'} handoff fixture`);
+  const from = String(input.from || 'Anchor');
+  const to = String(input.to || 'Loom');
+  const fromReference = String(input.fromReference || '').trim();
+  const toReference = String(input.toReference || '').trim();
+  const purpose = String(input.purpose || 'qualified Handoff regression fixture');
+  const createdAt = String(input.createdAt || '2026-08-23 12:00:00');
+  const requiredContext = sectionEntries(input.requiredContext, '- none');
+  const referenceContext = sectionEntries(input.referenceContext, '- none');
+  const retainedResponsibilities = sectionEntries(input.retainedResponsibilities, '- none');
+  const exclusions = sectionEntries(input.exclusionsAndDependencies, '- none');
+  const transferKind = String(input.transferKind || 'work');
+  const signalKind = String(input.signalKind || 'return');
+  const parent = input.parent && typeof input.parent === 'object' ? input.parent : null;
+  const parentBlock = parent ? `- Parent\n  - Parent Schema: [${String(parent.schemaId || 'tiinex.task.v1')}](${String(parent.schemaTarget || TASK_SCHEMA_TARGET)})\n  - Created At: ${String(parent.createdAt || '2026-08-23 11:00:00')}\n  - Trace: [Parent](${String(parent.trace || '../parent.trace.md')})\n  - Origin:\n${parent.includeRelative === false ? '' : `    - [relative](${String(parent.relative || parent.trace || '../parent.trace.md')})\n`}${parent.includeBrowseGit === false ? '' : `    - [browse + git](${String(parent.browseGit || 'https://github.com/Tiinex/site/blob/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/.topics/parent.trace.md')})\n`}\n` : '';
+  const parentIntegrityEntry = parent ? `- [sha256-base64url-c14n-v2](${C14N_V2_VALIDATOR_TARGET})\n  - Towards: [Parent](${String(parent.towards || parent.browseGit || 'https://github.com/Tiinex/site/blob/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/.topics/parent.trace.md')})\n  - Value: ${String(parent.targetValue || '')}\n\n` : '';
+  const unsigned = `# Continuity Context\n\n- Envelope Schema: [tiinex.root.v1](${ROOT_SCHEMA_TARGET})\n${parentBlock}- Current\n  - Current Schema: [tiinex.handoff.v1](${HANDOFF_SCHEMA_TARGET})\n  - Created At: ${createdAt}\n  - Authors: Fixture\n  - Why: Exercise portable Handoff qualification.\n  - Summary: ${title}.\n  - Status: local\n\n---\n\n# ${title}\n\n## Handoff Parties\n\n- Purpose: ${purpose}\n- From: ${from}\n- From Kind: role\n${fromReference ? `- From Reference: [${from}](${fromReference})\n` : ''}- To: ${to}\n- To Kind: role\n${toReference ? `- To Reference: [${to}](${toReference})\n` : ''}\n\n## Transfers\n\n- fixture-transfer\n  - Transfer Kind: ${transferKind}\n  - Description: bounded fixture work\n  - Boundary: fixture-only\n\n## Required Context\n\n${requiredContext}\n\n## Reference Context\n\n${referenceContext}\n\n## Retained Responsibilities\n\n${retainedResponsibilities}\n\n## Exclusions And Dependencies\n\n${exclusions}\n\n## Completion Expectation\n\n- Signal Kind: ${signalKind}\n- Signal Meaning: return the bounded fixture result\n- Return To: ${from}\n\n## Interpretation Limits\n\n- Does Not Mean: fixture routing grants semantic authority\n- Must Not Be Used To Claim: package placement or filenames override Tiinex qualification\n- Authority Limits: fixture only\n\n# Continuity Integrity\n\n${parentIntegrityEntry}- [sha256-base64url-c14n-v2](${C14N_V2_VALIDATOR_TARGET})\n  - Towards: self\n  - Value: \n`;
+  const sealed = sealC14nV2Self(unsigned);
+  if (sealed.state !== 'sealed') throw new Error(`qualified-handoff-fixture.seal-failed:${sealed.reason || sealed.state}`);
+  return `${sealed.markdown}\n`;
+}
+
+function sectionEntries(value, fallback) {
+  const text = value === undefined || value === null ? fallback : String(value);
+  return text.trim() || fallback;
+}