@tiinex/core 0.1.1

package/src/tooling/portable/reduction/reduction.eligibility.js

@@ -0,0 +1,191 @@
+import { resolveLineage } from '../../../lineage/lineage.resolve.js';
+import { portableFinding } from '../findings.js';
+import {
+  PORTABLE_REDUCTION_DESTRUCTIVE_CONTRACT,
+  PORTABLE_REDUCTION_DESTRUCTIVE_ELIGIBILITY_SCHEMA_ID,
+  identity,
+  normalizePath,
+  parseReductionEntries,
+  qualifyReductionRecord,
+  resolveUniqueRecord,
+  safeCode,
+  samePath,
+  sha256Text,
+  stableJson
+} from './reduction.shared.js';
+import {
+  assessCandidateIdentity, assessCurrentness, assessSurvivingDependencies, boundCandidate, boundCurrentnessFact,
+  boundLocator, boundParentProof, boundSnapshot, currentnessReissueFor, fixtureRetired, hasDisappearingChild,
+  immutableLocatorForLeaf, issue, normalizeCandidateSet, normalizeContract, normalizeList, normalizeParentProofs,
+  normalizeSnapshots, parentGraph, priorReceiptFingerprint, projectPostApply, proofSnapshotScopes, proveParentClosure,
+  scopeLabel, sharedClosureMaterial, snapshotMatchesScope, uniqueIssues
+} from './reduction.eligibility.helpers.js';
+
+
+const DESTRUCTIVE_ACTIONS = new Set(['delete', 'remove', 'prune']);
+
+export function projectReductionDestructiveEligibility(input = {}, material = {}, composition = null) {
+  const records = material.records || [];
+  const lineage = resolveLineage(records, { depth: 'portable-reduction-destructive-eligibility' });
+  const findings = [...(lineage.findings || [])];
+  const blockers = [];
+  const missingEvidence = [];
+  const ambiguities = [];
+  const rawCandidates = normalizeCandidateSet(input.candidateSet || input.destructiveCandidates || input.candidates || input.candidatePaths || []);
+  const snapshots = normalizeSnapshots(input.snapshots || input.workspaceSnapshots || input.repositorySnapshots || []);
+  const currentnessFacts = normalizeList(input.currentnessFacts || input.lifecycleFacts || input.currentness || []);
+  const immutableSources = normalizeList(input.immutableSources || input.sources || []);
+  const parentProofs = normalizeParentProofs(input.parentProofs || input.parentClosureProofs || []);
+  const endpointProofs = normalizeList(input.closureEndpoints || input.survivingBoundaries || []);
+  const reductionPath = normalizePath(input.reductionArtifactPath || input.reductionArtifact || input.reduction || '');
+  const reductionResolution = resolveUniqueRecord(records, reductionPath);
+  const reductionRecord = reductionResolution.record;
+  const reductionQualification = reductionRecord ? qualifyReductionRecord(reductionRecord, records) : null;
+  const reductionDigest = reductionRecord ? sha256Text(reductionRecord.markdown || '') : '';
+  const entries = reductionRecord ? parseReductionEntries(reductionRecord.markdown || '') : Object.freeze([]);
+  const graph = parentGraph(records, lineage, parentProofs);
+  const candidates = rawCandidates.map((candidate) => assessCandidateIdentity(candidate, records, immutableSources, snapshots));
+  const disappearing = candidates.filter((candidate) => DESTRUCTIVE_ACTIONS.has(candidate.action));
+  const semanticDisappearing = disappearing.filter((candidate) => candidate.classification.state === 'qualified' && candidate.classification.kind === 'semantic' && candidate.record);
+  const semanticDisappearingPaths = new Set(semanticDisappearing.map((candidate) => normalizePath(candidate.record.path || candidate.path)));
+  const leafEntrypoints = semanticDisappearing.filter((candidate) => !hasDisappearingChild(candidate.record, graph, semanticDisappearingPaths));
+  const proofLocators = parentProofs.flatMap((proof) => [proof.childLocator, proof.parentLocator].filter(Boolean));
+  const sourceLocators = [...immutableSources, ...proofLocators];
+
+  if (!reductionRecord && disappearing.length) missingEvidence.push(issue('qualified-pre-delete-reduction-required', reductionPath || '(empty)'));
+  else if (reductionRecord && !reductionQualification.qualified && disappearing.length) missingEvidence.push(issue('qualified-pre-delete-reduction-required', reductionQualification.reasons.join(', ')));
+
+  for (const candidate of candidates) {
+    if (candidate.identityState === 'ambiguous') ambiguities.push(issue('candidate-path-ambiguous', candidate.path));
+    else if (candidate.identityState === 'missing' && candidate.classification.kind === 'semantic') missingEvidence.push(issue('candidate-semantic-material-missing', candidate.path));
+    if (candidate.classification.state !== 'qualified') ambiguities.push(issue('candidate-classification-unresolved', candidate.path));
+    if (candidate.preimage.state === 'mismatch') blockers.push(issue('candidate-preimage-mismatch', candidate.path));
+    if (candidate.preimage.state === 'unresolved') missingEvidence.push(issue('candidate-preimage-unresolved', candidate.path));
+    if (candidate.classification.kind === 'fixture' && DESTRUCTIVE_ACTIONS.has(candidate.action) && !fixtureRetired(candidate, input.fixtureRetirements || [])) blockers.push(issue('fixture-required-deletion', candidate.path));
+  }
+
+  const leafProofs = [];
+  const covered = new Set();
+  if (reductionRecord && reductionQualification?.qualified) {
+    for (const leaf of leafEntrypoints) {
+      const matches = entries.filter((entry) => samePath(entry.leafPath, leaf.record.path));
+      if (matches.length === 0) { blockers.push(issue('disappearing-leaf-declaration-missing', leaf.record.path)); continue; }
+      if (matches.length > 1) { ambiguities.push(issue('disappearing-leaf-declaration-ambiguous', leaf.record.path)); continue; }
+      const entry = matches[0];
+      covered.add(normalizePath(leaf.record.path));
+      if (!entry.disposition) blockers.push(issue('disposition-required', leaf.record.path));
+      if (!entry.reason) blockers.push(issue('reason-required', leaf.record.path));
+      if (!entry.collapseToPath) blockers.push(issue('historical-closure-endpoint-required', leaf.record.path));
+      const leafLocator = immutableLocatorForLeaf(leaf.record, entry, sourceLocators);
+      if (!leafLocator.qualified) missingEvidence.push(issue('immutable-leaf-source-unresolved', leaf.record.path));
+      const proof = proveParentClosure({ leaf: leaf.record, boundaryPath: entry.collapseToPath, graph, disappearingPaths: semanticDisappearingPaths, records, sourceLocators, endpointProofs, snapshots });
+      leafProofs.push(Object.freeze({
+        leaf: identity(leaf.record),
+        immutableLocator: leafLocator,
+        disposition: entry.disposition,
+        reason: entry.reason,
+        historicalClosureEndpoint: entry.collapseToPath,
+        placementParent: reductionQualification.parentPath,
+        parentSpan: proof,
+        reissue: currentnessReissueFor(leaf.record.path, currentnessFacts)
+      }));
+      if (proof.state === 'ambiguous') ambiguities.push(issue(proof.code || 'parent-closure-ambiguous', leaf.record.path));
+      else if (proof.state === 'unresolved') missingEvidence.push(issue(proof.code || 'parent-closure-unresolved', leaf.record.path));
+      else if (proof.state === 'blocked') blockers.push(issue(proof.code || 'parent-closure-blocked', leaf.record.path));
+      if (proof.qualified) for (const item of proof.path.slice(0, -1)) covered.add(normalizePath(item));
+    }
+
+    for (const entry of entries) {
+      const matchedCandidate = candidates.find((candidate) => candidate.record && samePath(candidate.record.path, entry.leafPath));
+      if (matchedCandidate && !DESTRUCTIVE_ACTIONS.has(matchedCandidate.action)) blockers.push(issue('reduction-leaf-retained-by-candidate-set', entry.leafPath));
+      else if (!matchedCandidate && entry.leafPath) blockers.push(issue('reduction-leaf-not-in-destructive-set', entry.leafPath));
+    }
+  }
+
+  for (const candidate of semanticDisappearing) {
+    const candidatePath = normalizePath(candidate.record.path || candidate.path);
+    if (!covered.has(candidatePath)) blockers.push(issue('uncovered-disappearing-semantic-artifact', candidatePath));
+    assessCurrentness(candidate, currentnessFacts, records, semanticDisappearingPaths, blockers, missingEvidence, ambiguities);
+  }
+
+  assessSurvivingDependencies(records, graph, semanticDisappearingPaths, currentnessFacts, blockers, ambiguities);
+  const requiredSnapshotScopes = proofSnapshotScopes(candidates, leafProofs);
+  for (const scope of requiredSnapshotScopes) {
+    const match = snapshots.filter((snapshot) => snapshotMatchesScope(snapshot, scope));
+    if (match.length === 0) missingEvidence.push(issue('proof-snapshot-missing', scopeLabel(scope)));
+    else if (match.length > 1) ambiguities.push(issue('proof-snapshot-ambiguous', scopeLabel(scope)));
+    else if (!match[0].qualified) missingEvidence.push(issue('proof-snapshot-unqualified', scopeLabel(scope)));
+    else if (scope.commit && match[0].commit && scope.commit !== match[0].commit) missingEvidence.push(issue('proof-snapshot-immutable-ref-mismatch', scopeLabel(scope)));
+  }
+
+  const contract = normalizeContract(input.contractIdentity || input.qualificationContract || PORTABLE_REDUCTION_DESTRUCTIVE_CONTRACT);
+  if (!contract.qualified) missingEvidence.push(issue('qualification-contract-unqualified', contract.id || '(empty)'));
+  const boundCandidateSet = candidates.map(boundCandidate).sort((a, b) => `${a.repository}|${a.workspace}|${a.path}|${a.action}`.localeCompare(`${b.repository}|${b.workspace}|${b.path}|${b.action}`));
+  const boundSnapshots = snapshots.map(boundSnapshot).sort((a, b) => `${a.repository}|${a.workspace}|${a.commit}`.localeCompare(`${b.repository}|${b.workspace}|${b.commit}`));
+  const boundCurrentness = currentnessFacts.map(boundCurrentnessFact).sort((a, b) => `${a.target}|${a.state}`.localeCompare(`${b.target}|${b.state}`));
+  const candidateSetDigest = sha256Text(stableJson(boundCandidateSet));
+  const boundInputs = Object.freeze({
+    reduction: Object.freeze({ path: reductionPath, sha256: reductionDigest }),
+    snapshots: Object.freeze(boundSnapshots),
+    candidateSet: Object.freeze(boundCandidateSet),
+    lifecycleCurrentnessBasis: Object.freeze(boundCurrentness),
+    qualificationContract: contract.bound,
+    proofMaterial: Object.freeze({
+      parentProofsSha256: sha256Text(stableJson(parentProofs.map(boundParentProof))),
+      immutableSourcesSha256: sha256Text(stableJson(sourceLocators.map(boundLocator))),
+      compositionFingerprint: String(composition?.fingerprint || '')
+    })
+  });
+  const inputFingerprint = sha256Text(stableJson(boundInputs));
+  const priorFingerprint = priorReceiptFingerprint(input.priorReceipt || input.receipt || input.qualificationReceipt);
+  if (priorFingerprint && priorFingerprint !== inputFingerprint) blockers.push(issue('receipt-input-fingerprint-mismatch', `prior=${priorFingerprint} current=${inputFingerprint}`));
+
+  const postApply = projectPostApply(input.postApply || input.postApplyAudit || null, candidateSetDigest);
+  const requested = rawCandidates.length > 0;
+  const state = !requested ? 'not-requested'
+    : blockers.length ? 'blocked'
+      : missingEvidence.length || ambiguities.length ? 'unresolved'
+        : 'eligible';
+  const destructiveEligible = state === 'eligible';
+
+  for (const item of blockers) findings.push(portableFinding('error', `portable.reduction-eligibility.${safeCode(item.code)}`, item.detail, { ref: reductionPath }));
+  for (const item of missingEvidence) findings.push(portableFinding('warning', `portable.reduction-eligibility.${safeCode(item.code)}`, item.detail, { ref: reductionPath }));
+  for (const item of ambiguities) findings.push(portableFinding('warning', `portable.reduction-eligibility.${safeCode(item.code)}`, item.detail, { ref: reductionPath }));
+  if (requested && state === 'unresolved') findings.push(portableFinding('error', 'portable.reduction-eligibility.unresolved-fail-closed', 'Destructive eligibility is unresolved; destructive apply remains forbidden.', { ref: reductionPath }));
+  if (postApply.state === 'mismatch') findings.push(portableFinding('error', 'portable.reduction-eligibility.post-apply-simulation-mismatch', 'Simulated post-apply material does not match the exact qualified candidate set.', { ref: reductionPath }));
+
+  return Object.freeze({
+    schema: PORTABLE_REDUCTION_DESTRUCTIVE_ELIGIBILITY_SCHEMA_ID,
+    state,
+    destructiveEligible,
+    reduction: Object.freeze({ requestedPath: reductionPath, record: reductionRecord ? identity(reductionRecord) : null, qualification: reductionQualification, digest: reductionDigest, placementParent: reductionQualification?.parentPath || '' }),
+    snapshots: Object.freeze(snapshots),
+    candidateSet: Object.freeze(candidates),
+    candidateSetDigest,
+    disappearingSemanticSet: Object.freeze(semanticDisappearing.map((candidate) => identity(candidate.record))),
+    leafEntrypoints: Object.freeze(leafProofs),
+    sharedClosureMaterial: Object.freeze(sharedClosureMaterial(leafProofs)),
+    currentnessBasis: Object.freeze(currentnessFacts),
+    contract,
+    blockers: Object.freeze(uniqueIssues(blockers)),
+    missingEvidence: Object.freeze(uniqueIssues(missingEvidence)),
+    ambiguities: Object.freeze(uniqueIssues(ambiguities)),
+    receipt: Object.freeze({ schema: 'tiinex.portable.reduction-destructive-eligibility.receipt.v1', state, inputFingerprint, candidateSetDigest, boundInputs, stalePriorReceipt: Boolean(priorFingerprint && priorFingerprint !== inputFingerprint), reusableOnlyForExactBoundInputs: true }),
+    postApply,
+    boundary: Object.freeze({
+      adapterNeutral: true,
+      planningAndQualificationOnly: true,
+      sourceMutation: false,
+      remoteWrite: false,
+      destructiveApplyImplemented: false,
+      destructiveApplyAuthorized: false,
+      eligibleIsNecessaryButNotSufficient: true,
+      ordinaryReductionValidityDependsOnEligibility: false,
+      placementParentIsHistoricalClosureEndpoint: false,
+      lifecycleFactsAreEvidenceNotDeleteAuthority: true,
+      candidateSetDerivedCoverageNotReductionProse: true
+    }),
+    findings: Object.freeze(findings)
+  });
+}
+

package/src/tooling/portable/reduction/reduction.operations.js

@@ -0,0 +1,30 @@
+import { portableOperationResult as operationResult } from '../operation.result.js';
+import { preflightPortableReduction } from './reduction.preflight.js';
+
+export function preflightPortableReductionOperation(input = {}, options = {}) {
+  const preflight = preflightPortableReduction(input, options);
+  return operationResult('reduction-preflight', {
+    status: preflight.status,
+    destructiveEligible: preflight.destructiveEligible,
+    composition: preflight.composition,
+    eligibility: preflight.eligibility,
+    inventory: preflight.inventory,
+    reduction: preflight.reduction,
+    candidates: preflight.candidates,
+    summary: preflight.summary,
+    boundary: preflight.boundary,
+    findings: preflight.findings || []
+  });
+}
+
+export const portableReductionOperationDescriptors = Object.freeze([
+  Object.freeze({
+    name: 'reduction-preflight',
+    description: 'Project ordinary hierarchical Reduction composition/recovery and, only when an exact destructive candidate set is supplied, a separate fail-closed eligible|blocked|unresolved destructive-lineage qualification bound to exact inputs. The operation is read-only and never authorizes apply.',
+    safety: 'planning-only-read-only',
+    inputSchema: 'tiinex.portable.reduction-preflight.request.v1',
+    sourceMutation: false,
+    remoteWrite: false,
+    handler: preflightPortableReductionOperation
+  })
+]);

package/src/tooling/portable/reduction/reduction.preflight.js

@@ -0,0 +1,85 @@
+import { inferRecordMaterialRole, isDiscoveryWorkLeafEligible, MaterialRole } from '../../../workspaces/workspace.materialRole.js';
+import { normalizePortableInput } from '../input/portable.input.js';
+import { projectReductionComposition } from './reduction.composition.js';
+import { projectReductionDestructiveEligibility } from './reduction.eligibility.js';
+import { PORTABLE_REDUCTION_PREFLIGHT_SCHEMA_ID } from './reduction.shared.js';
+
+const FIXTURE_RE = /(^|\/)(?:fixtures?|test-fixtures?|__fixtures__)(\/|$)|\.fixture\./i;
+
+export { PORTABLE_REDUCTION_PREFLIGHT_SCHEMA_ID } from './reduction.shared.js';
+
+export function preflightPortableReduction(input = {}, options = {}) {
+  const material = normalizePortableInput(input.materials || input);
+  const composition = projectReductionComposition(input, material, options);
+  const eligibility = projectReductionDestructiveEligibility(input, material, composition, options);
+  const inventory = buildInventory(material.records || []);
+  const findings = Object.freeze([...(material.findings || []), ...(composition.findings || []), ...(eligibility.findings || [])]);
+  const requested = eligibility.state !== 'not-requested';
+  const status = eligibility.state === 'eligible' ? 'preflight-qualified'
+    : requested ? 'blocked'
+      : ['qualified', 'qualified-with-known-loss'].includes(composition.state) ? 'projection-qualified' : 'unresolved';
+  const summary = Object.freeze({
+    records: material.records?.length || 0,
+    semanticRecords: inventory.counts.semantic,
+    explicitCandidates: eligibility.candidateSet.length,
+    disappearingSemantic: eligibility.disappearingSemanticSet.length,
+    leafEntrypoints: eligibility.leafEntrypoints.length,
+    compositionNodes: composition.nodes.length,
+    compositionHops: composition.hops.length,
+    eligibilityState: eligibility.state
+  });
+  return Object.freeze({
+    schema: PORTABLE_REDUCTION_PREFLIGHT_SCHEMA_ID,
+    status,
+    destructiveEligible: eligibility.destructiveEligible,
+    composition,
+    eligibility,
+    inventory,
+    reduction: Object.freeze({ ...eligibility.reduction, entries: Object.freeze(eligibility.leafEntrypoints.map((item) => Object.freeze({ leafPath: item.leaf.path, collapseToPath: item.historicalClosureEndpoint, disposition: item.disposition, reason: item.reason }))) }),
+    candidates: eligibility.candidateSet,
+    summary,
+    findings,
+    boundary: Object.freeze({
+      adapterNeutral: true,
+      sharedConsumers: Object.freeze(['Viewer', 'CLI', 'LLM', 'VS Code']),
+      planningOnly: true,
+      sourceMutation: false,
+      remoteWrite: false,
+      destructiveApplyImplemented: false,
+      destructiveApplyAuthorized: false,
+      ordinaryReductionAuthoritySeparate: true,
+      lifecycleLexicalStatusIsDestructivePolicy: false,
+      placementParentEqualsHistoricalClosureEndpoint: false,
+      canonicalReductionSchemaAuthorityChanged: false,
+      destructiveEligibilityMeaning: 'eligible is exact fail-closed qualification evidence only; a separate future apply capability must enforce current state, authorization, approvals, and mutation gates'
+    })
+  });
+}
+
+function buildInventory(records = []) {
+  const items = records.map((record) => {
+    const role = inferRecordMaterialRole(record);
+    const fixture = record.fixture === true || record.requiredFixture === true || FIXTURE_RE.test(String(record.path || '').replace(/\\/g, '/'));
+    const semantic = isDiscoveryWorkLeafEligible(record);
+    return Object.freeze({
+      id: String(record.id || ''), path: String(record.path || ''), schemaId: String(record.schemaId || ''),
+      materialRole: role, semantic, fixture,
+      observedLifecycleStatus: String(record.lifecycleStatus || record.currentStatus || record.status || ''),
+      destructiveCurrentnessAuthority: 'none-without-qualified-normalized-currentness-input'
+    });
+  });
+  return Object.freeze({
+    items: Object.freeze(items),
+    counts: Object.freeze({
+      total: items.length,
+      semantic: items.filter((item) => item.semantic).length,
+      fixture: items.filter((item) => item.fixture).length,
+      leafRole: items.filter((item) => item.materialRole === MaterialRole.leaf).length,
+      schemaDefinition: items.filter((item) => item.materialRole === MaterialRole.schemaDefinition).length,
+      supporting: items.filter((item) => item.materialRole === MaterialRole.supporting).length,
+      workspaceArtifact: items.filter((item) => item.materialRole === MaterialRole.workspaceArtifact).length,
+      unknown: items.filter((item) => item.materialRole === MaterialRole.unknown).length
+    }),
+    boundary: 'Inventory is classification evidence only. Lexical lifecycle/status observations are not destructive currentness authority.'
+  });
+}

package/src/tooling/portable/reduction/reduction.shared.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { auditPortableRecord } from '../audit/audit.capability.js';
+import { isDiscoveryWorkLeafEligible } from '../../../workspaces/workspace.materialRole.js';
+
+export const PORTABLE_REDUCTION_PREFLIGHT_SCHEMA_ID = 'tiinex.portable.reduction-preflight.v1';
+export const PORTABLE_REDUCTION_COMPOSITION_SCHEMA_ID = 'tiinex.portable.reduction-composition.v1';
+export const PORTABLE_REDUCTION_DESTRUCTIVE_ELIGIBILITY_SCHEMA_ID = 'tiinex.portable.reduction-destructive-eligibility.v1';
+export const PORTABLE_REDUCTION_DESTRUCTIVE_CONTRACT = Object.freeze({
+  id: 'tiinex.portable.reduction-destructive-eligibility.v1',
+  version: 1,
+  authority: 'shared-tooling-projection-contract',
+  canonicalSchemaAuthorityChanged: false
+});
+
+export const GITHUB_IMMUTABLE_BLOB_RE = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([0-9a-f]{40})\/(.+)$/i;
+
+export function sha256Text(value = '') { return createHash('sha256').update(String(value), 'utf8').digest('hex'); }
+export 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])]));
+}
+
+export function normalizePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '').trim(); }
+export function safeCode(value = '') { return String(value || 'unresolved').toLowerCase().replace(/[^a-z0-9.-]+/g, '-').replace(/^-+|-+$/g, ''); }
+export function escapeRegExp(value = '') { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+export function linkPath(value = '') {
+  const text = String(value || '').trim();
+  const github = text.match(GITHUB_IMMUTABLE_BLOB_RE);
+  if (github) return normalizePath(github[4]);
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) {
+    try { return normalizePath(new URL(text).pathname); } catch { return ''; }
+  }
+  return normalizePath(text.split('#')[0].split('?')[0]);
+}
+
+export function identity(record = {}) {
+  return Object.freeze({ id: String(record.id || record.path || ''), path: String(record.path || ''), title: String(record.title || ''), schemaId: String(record.schemaId || '') });
+}
+
+export function resolveUniqueRecord(records = [], requestedPath = '') {
+  const wanted = normalizePath(requestedPath);
+  if (!wanted) return Object.freeze({ state: 'missing', record: null });
+  const exact = records.filter((record) => normalizePath(record.path) === wanted || normalizePath(record.id) === wanted);
+  if (exact.length === 1) return Object.freeze({ state: 'exact', record: exact[0] });
+  if (exact.length > 1) return Object.freeze({ state: 'ambiguous', record: null });
+  const suffix = records.filter((record) => normalizePath(record.path).endsWith(`/${wanted}`));
+  if (suffix.length === 1) return Object.freeze({ state: 'suffix', record: suffix[0] });
+  return Object.freeze({ state: suffix.length > 1 ? 'ambiguous' : 'missing', record: null });
+}
+
+export function qualifyRecord(record = {}) {
+  if (!record) return Object.freeze({ state: 'missing', qualified: false, reasons: Object.freeze(['record-missing']), audit: null });
+  const audit = auditPortableRecord(record);
+  const reasons = [];
+  if (!record.hasContinuityContext) reasons.push('continuity-context-missing');
+  if (!record.hasIntegrity) reasons.push('integrity-missing');
+  if (audit.qualification?.exact !== true || audit.qualification?.moduleExact !== true) reasons.push('non-exact-schema-validation');
+  if (audit.status !== 'readable') reasons.push(`audit-status:${audit.status || 'unknown'}`);
+  if ((audit.findings || []).some((finding) => finding.severity === 'error')) reasons.push('audit-error');
+  return Object.freeze({ state: reasons.length ? 'unresolved' : 'qualified', qualified: reasons.length === 0, reasons: Object.freeze(reasons), audit });
+}
+
+export function qualifyReductionRecord(record = {}, records = []) {
+  if (!record) return Object.freeze({ qualified: false, state: 'missing', digest: '', parentPath: '', parent: null, reasons: Object.freeze(['reduction-artifact-missing']), audit: null });
+  const base = qualifyRecord(record);
+  const reasons = [...base.reasons];
+  if (String(record.schemaId || '') !== 'tiinex.reduction.v1') reasons.push(`schema:${record.schemaId || 'missing'}`);
+  const parentPath = normalizePath(record.trace || '');
+  const parentResolution = parentPath ? resolveUniqueRecord(records, parentPath) : { state: 'missing', record: null };
+  if (!parentPath) reasons.push('reduction-parent-required');
+  else if (parentResolution.state === 'ambiguous') reasons.push('reduction-parent-ambiguous');
+  else if (!parentResolution.record) reasons.push('reduction-parent-not-loaded');
+  else {
+    const parentQualification = qualifyRecord(parentResolution.record);
+    if (!isDiscoveryWorkLeafEligible(parentResolution.record)) reasons.push('reduction-parent-not-semantic-work-artifact');
+    if (!parentQualification.qualified) reasons.push('reduction-parent-unqualified');
+  }
+  return Object.freeze({
+    qualified: reasons.length === 0,
+    state: reasons.length ? 'unresolved' : 'qualified',
+    digest: sha256Text(record.markdown || ''),
+    parentPath,
+    parent: parentResolution.record ? identity(parentResolution.record) : null,
+    reasons: Object.freeze([...new Set(reasons)]),
+    audit: base.audit
+  });
+}
+
+export function sectionText(markdown = '', heading = '') {
+  const source = String(markdown || '');
+  const name = escapeRegExp(heading);
+  return String(source.match(new RegExp(`(?:^|\\n)##\\s+${name}\\s*\\r?\\n([\\s\\S]*?)(?=\\n##\\s+|\\n#\\s+|$)`, 'i'))?.[1] || '').trim();
+}
+
+export function markdownLinks(markdown = '') {
+  return Object.freeze([...String(markdown || '').matchAll(/\[([^\]]+)\]\(([^)]+)\)/g)].map((match) => Object.freeze({ label: String(match[1] || '').trim(), target: String(match[2] || '').trim(), path: linkPath(match[2] || '') })));
+}
+
+export function parseReductionEntries(markdown = '') {
+  const section = String(markdown || '').match(/###\s+Reduced Leaves\s*\/\s*Expansion Boundary\s*\n([\s\S]*?)(?=\n##\s|\n#\s|$)/i)?.[1] || '';
+  if (!section) return Object.freeze([]);
+  const starts = [...section.matchAll(/^\s*-\s+\*\*(.+?)\*\*\s*$/gm)];
+  const entries = [];
+  for (let index = 0; index < starts.length; index += 1) {
+    const start = starts[index].index ?? 0;
+    const end = index + 1 < starts.length ? starts[index + 1].index ?? section.length : section.length;
+    const block = section.slice(start, end);
+    const leaf = parseLabeledLink(block, 'Leaf');
+    const collapse = parseLabeledLink(block, 'Collapse To');
+    entries.push(Object.freeze({
+      title: String(starts[index][1] || '').trim(),
+      leafLabel: leaf.label,
+      leafTarget: leaf.target,
+      leafPath: linkPath(leaf.target || leaf.label),
+      collapseToLabel: collapse.label,
+      collapseToTarget: collapse.target,
+      collapseToPath: linkPath(collapse.target || collapse.label),
+      disposition: labeledCodeOrText(block, 'Disposition'),
+      reason: labeledText(block, 'Why'),
+      scope: labeledText(block, 'Expansion Span') || labeledText(block, 'Scope')
+    }));
+  }
+  return Object.freeze(entries);
+}
+
+function parseLabeledLink(block, label) {
+  const match = block.match(new RegExp(`^\\s*-\\s+${escapeRegExp(label)}:\\s+\\[([^\\]]+)\\]\\(([^)]+)\\)\\s*$`, 'im'));
+  return Object.freeze({ label: String(match?.[1] || '').trim(), target: String(match?.[2] || '').trim() });
+}
+function labeledCodeOrText(block, label) { return labeledText(block, label).replace(/^`|`$/g, '').trim(); }
+function labeledText(block, label) { return String(block.match(new RegExp(`^\\s*-\\s+${escapeRegExp(label)}:\\s+(.+?)\\s*$`, 'im'))?.[1] || '').trim(); }
+
+export function locatorFromValue(value = {}) {
+  if (typeof value === 'string') {
+    const github = value.match(GITHUB_IMMUTABLE_BLOB_RE);
+    if (!github) return unqualifiedLocator('immutable-locator-unqualified');
+    return Object.freeze({ qualified: true, state: 'immutable-git', provider: 'github', repository: `${github[1]}/${github[2]}`, commit: github[3].toLowerCase(), workspace: '', path: normalizePath(github[4]), permalink: value, digest: '', basis: 'explicit-commit-pinned-permalink' });
+  }
+  const repository = String(value.repository || value.repo || '').trim();
+  const commit = String(value.commit || value.sha || value.ref || '').trim().toLowerCase();
+  const workspace = String(value.workspace || value.workspaceId || '').trim();
+  const sourcePath = normalizePath(value.path || value.sourcePath || '');
+  const permalink = String(value.permalink || value.url || '').trim();
+  const digest = String(value.digest || value.sha256 || '').replace(/^sha256:/, '').trim().toLowerCase();
+  const immutable = value.immutable === true || /^[0-9a-f]{40}$/i.test(commit);
+  const qualified = Boolean(immutable && /^[0-9a-f]{40}$/i.test(commit) && repository && sourcePath);
+  return Object.freeze({ qualified, state: qualified ? 'immutable-git' : 'unqualified', provider: String(value.provider || 'explicit'), repository, commit, workspace, path: sourcePath, permalink, digest, basis: value.basis || '', blocker: qualified ? '' : 'immutable-locator-unqualified' });
+}
+
+export function locatorForRecord(record = {}, supplied = []) {
+  const wanted = new Set([normalizePath(record.path), path.basename(normalizePath(record.path))].filter(Boolean));
+  const explicit = supplied.find((item) => wanted.has(normalizePath(item.path || item.candidatePath || item.target || '')) || wanted.has(path.basename(normalizePath(item.path || item.candidatePath || item.target || ''))));
+  if (explicit) return locatorFromValue(explicit);
+  const source = record.source || {};
+  if (source.repository && /^[0-9a-f]{40}$/i.test(String(source.commit || source.ref || '')) && source.path) return locatorFromValue({ repository: source.repository, commit: source.commit || source.ref, workspace: source.workspace || '', path: source.path, immutable: true, permalink: source.permalink || '', basis: source.boundary || 'explicit-record-source' });
+  return unqualifiedLocator('immutable-locator-missing');
+}
+
+export function locatorMatchesRecord(locator = {}, record = {}) {
+  if (!locator?.qualified || !record) return false;
+  const recordPath = normalizePath(record.path || '');
+  return Boolean(recordPath === normalizePath(locator.path) || recordPath.endsWith(`/${normalizePath(locator.path)}`) || path.basename(recordPath) === path.basename(normalizePath(locator.path)));
+}
+
+export function samePath(a = '', b = '') {
+  const left = normalizePath(a); const right = normalizePath(b);
+  return Boolean(left && right && (left === right || left.endsWith(`/${right}`) || right.endsWith(`/${left}`)));
+}
+
+function unqualifiedLocator(blocker) { return Object.freeze({ qualified: false, state: 'missing', provider: '', repository: '', commit: '', workspace: '', path: '', permalink: '', digest: '', basis: '', blocker }); }

package/src/tooling/portable/schema/bootstrap/canonical.pack.js

@@ -0,0 +1,24 @@
+import { fileURLToPath } from 'node:url';
+
+export const PORTABLE_CANONICAL_BOOTSTRAP_DOCS_COMMIT = '3988951208eb9a8926e84ab42625d4b42fa00c2d';
+export const PORTABLE_CANONICAL_BOOTSTRAP_ROOT = fileURLToPath(new URL(`./docs-${PORTABLE_CANONICAL_BOOTSTRAP_DOCS_COMMIT}/`, import.meta.url));
+
+export const portableCanonicalBootstrapRuntime = Object.freeze({
+  defaultSchemaMaterialPaths: Object.freeze([PORTABLE_CANONICAL_BOOTSTRAP_ROOT]),
+  defaultSchemaSource: Object.freeze({
+    repository: 'Tiinex/docs',
+    commit: PORTABLE_CANONICAL_BOOTSTRAP_DOCS_COMMIT,
+    sourcePathPrefix: '.topics/.schemas'
+  }),
+  defaultSchemaProviderSource: Object.freeze({
+    id: 'tiinex-docs',
+    repository: 'Tiinex/docs',
+    ref: 'master',
+    source: 'canonical-bootstrap-runtime-profile'
+  }),
+  defaultCarrierProfile: Object.freeze({
+    id: 'tiinex-foundation',
+    requiredMajorWorkspaceIds: Object.freeze(['business', 'docs', 'site']),
+    source: 'canonical-bootstrap-runtime-profile'
+  })
+});