@tiinex/app 0.1.1

package/src/transitions/transition.definitionRegistry.js

@@ -0,0 +1,355 @@
+import { parseArtifactMarkdown } from '@tiinex/core/artifacts/artifact.parse.js';
+import { schemaIdForRecord } from '@tiinex/core/schemas/schema.identity.js';
+import '../sources/source.identity.js';
+import { compilePortableSchemaContractChain } from '@tiinex/core/tooling/portable/schema/contract.compile.js';
+import { projectPortableContractInstance } from '@tiinex/core/tooling/portable/schema/contract.project.js';
+import { resolvePortableSchemaChainMaterial } from '@tiinex/core/tooling/portable/providers/schema.providers.js';
+import { CANONICAL_TRANSITION_DEFINITION_SCHEMA_ID, LEGACY_TRANSITION_SHORTHAND_CONTRACT_ID } from './transition.legacyShorthand.js';
+import { collectTransitionDefinitionRegistryRecords, readTransitionDefinitionRepresentationQualification, readTransitionDefinitionSchemaQualification, registryIdentityForRecord, sourceBoundaryIdentity, sourceBoundarySignature } from './transition.definitionRegistryAggregation.js';
+import { projectTransitionDefinitionPortableRead } from './transition.definitionReadProjection.js';
+
+export const TRANSITION_DEFINITION_REGISTRY_SCHEMA_ID = 'tiinex.site.transition-definition-registry.v1';
+export const TRANSITION_DEFINITION_READ_MODEL_SCHEMA_ID = 'tiinex.site.transition-definition-read-model.v1';
+
+const ROOT_SCHEMA_ID = 'tiinex.root.v1';
+
+export async function buildTransitionDefinitionRegistryFromPortableMaterial(input = {}) {
+  const resolution = await resolvePortableSchemaChainMaterial({
+    schemaId: CANONICAL_TRANSITION_DEFINITION_SCHEMA_ID,
+    records: Array.isArray(input.schemaRecords) ? input.schemaRecords : [],
+    files: Array.isArray(input.schemaFiles) ? input.schemaFiles : [],
+    schemaCache: input.schemaCache,
+    providerResponses: input.providerResponses
+  }, { providers: [] });
+  const registry = buildTransitionDefinitionRegistry({
+    ...input,
+    schemaMaterial: undefined,
+    schemaMaterials: resolution.materials?.files || [],
+    schemaContracts: undefined,
+    schemaRecords: []
+  });
+  return Object.freeze({
+    ...registry,
+    schemaMaterialResolution: Object.freeze({
+      status: resolution.status,
+      nodes: Object.freeze([...(resolution.nodes || [])]),
+      providerRequest: resolution.providerRequest || null,
+      findings: Object.freeze([...(resolution.findings || [])])
+    })
+  });
+}
+
+export function buildTransitionDefinitionRegistry(input = {}) {
+  const records = collectTransitionDefinitionRegistryRecords(input, declaredRecordSchemaId, recordSchemaId, CANONICAL_TRANSITION_DEFINITION_SCHEMA_ID);
+  const definitions = records
+    .filter((record) => isCanonicalTransitionDefinitionRecord(record))
+    .map((record) => buildTransitionDefinitionReadModel(record, input))
+    .sort(compareReadModels);
+  return Object.freeze({
+    schema: TRANSITION_DEFINITION_REGISTRY_SCHEMA_ID,
+    count: definitions.length,
+    definitions: Object.freeze(definitions),
+    boundary: Object.freeze({
+      readOnly: true,
+      applicability: 'not-evaluated',
+      execution: 'not-authorized',
+      mutation: false
+    })
+  });
+}
+
+export function buildTransitionDefinitionReadModel(record = {}, input = {}) {
+  const schemaChain = compileDefinitionSchemaChain(input);
+  const chainQualification = schemaChain?.lineageQualification || unresolvedQualification('Canonical Root→Transition Definition schema material is not fully supplied.');
+  const completeAuthority = chainQualification.state === 'valid' && chainQualification.complete === true;
+  const instanceProjection = schemaChain
+    ? projectPortableContractInstance({
+        markdown: String(record.markdown || ''),
+        compiledContract: schemaChain,
+        resolvers: input.resolvers || {}
+      })
+    : unresolvedInstanceProjection();
+  const validation = instanceProjection.validation;
+  const portableRead = projectTransitionDefinitionPortableRead(instanceProjection);
+  const ordinaryReadAuthority = ordinaryReadAuthorityQualification(schemaChain);
+  const representationQualification = readTransitionDefinitionRepresentationQualification(record);
+  const schemaQualification = readTransitionDefinitionSchemaQualification(record, CANONICAL_TRANSITION_DEFINITION_SCHEMA_ID);
+  const diagnostics = buildDiagnostics(chainQualification, validation, record, schemaQualification, ordinaryReadAuthority);
+  const validationReadable = validation.status !== 'structurally-invalid';
+  const contractReadValid = validation.status === 'valid' || validation.status === 'valid-with-preserved-unknowns';
+  const canonicalSchemaClean = schemaQualification.state === 'equivalent'
+    && schemaQualification.declaredSchemaIds.length === 1
+    && schemaQualification.declaredSchemaIds[0] === CANONICAL_TRANSITION_DEFINITION_SCHEMA_ID;
+  const canonicalReadQualified = canonicalSchemaClean
+    && completeAuthority
+    && representationQualification.state === 'equivalent'
+    && contractReadValid
+    && ordinaryReadAuthority.state === 'available';
+  return Object.freeze({
+    schema: TRANSITION_DEFINITION_READ_MODEL_SCHEMA_ID,
+    artifact: artifactIdentity(record),
+    source: sourceIdentity(record),
+    transitionIdentity: portableRead.transitionIdentity,
+    ordinaryProjection: portableRead.ordinaryProjection,
+    ordinaryReadAuthority,
+    schemaChain: Object.freeze({
+      schemaId: schemaChain?.schemaId || CANONICAL_TRANSITION_DEFINITION_SCHEMA_ID,
+      lineage: Object.freeze([...(chainQualification.lineage || [])]),
+      suppliedLineage: Object.freeze([...(schemaChain?.suppliedLineage || [])]),
+      state: chainQualification.state,
+      complete: chainQualification.complete === true,
+      completeAuthority
+    }),
+    contractValidation: Object.freeze({
+      status: validation.status,
+      states: validation.states || Object.freeze({ primary: 'unresolved', counts: Object.freeze({ unresolved: 1 }) })
+    }),
+    inputRoles: portableRead.inputRoles,
+    outputRoles: portableRead.outputRoles,
+    lifecycleEffects: portableRead.lifecycleEffects,
+    parentEffects: portableRead.parentEffects,
+    relationEffects: portableRead.relationEffects,
+    destinationBindings: portableRead.destinationBindings,
+    outputPlacements: portableRead.outputPlacements,
+    representationQualification,
+    schemaQualification,
+    diagnostics: Object.freeze(diagnostics),
+    readable: validationReadable,
+    canonicalReadQualified,
+    schemaAuthorityComplete: completeAuthority,
+    applicability: 'not-evaluated',
+    executable: false,
+    executionReason: 'read-only canonical Transition Definition consumption seam; applicability and execution are outside this slice'
+  });
+}
+
+export function isCanonicalTransitionDefinitionRecord(record = {}) {
+  if (String(record?.schema || '') === LEGACY_TRANSITION_SHORTHAND_CONTRACT_ID) return false;
+  const aggregation = record.registryAggregation || {};
+  if (aggregation.canonicalSchemaObserved === true) return true;
+  return declaredRecordSchemaId(record) === CANONICAL_TRANSITION_DEFINITION_SCHEMA_ID;
+}
+
+function compileDefinitionSchemaChain(input = {}) {
+  const supplied = suppliedSchemaMaterial(input);
+  const root = supplied.get(ROOT_SCHEMA_ID);
+  const transition = supplied.get(CANONICAL_TRANSITION_DEFINITION_SCHEMA_ID);
+  if (!transition) return null;
+  return compilePortableSchemaContractChain(root ? [root, transition] : [transition]);
+}
+
+function suppliedSchemaMaterial(input = {}) {
+  const out = new Map();
+  const supplied = input.schemaMaterial || input.schemaMaterials || input.schemaContracts || {};
+  if (Array.isArray(supplied)) {
+    for (const item of supplied) addSchemaMaterial(out, item);
+  } else {
+    for (const [schemaId, item] of Object.entries(supplied || {})) addSchemaMaterial(out, typeof item === 'string' ? { schemaId, markdown: item } : { schemaId, ...item });
+  }
+  for (const record of Array.isArray(input.schemaRecords) ? input.schemaRecords : []) addSchemaMaterial(out, record);
+  return out;
+}
+
+function addSchemaMaterial(out, item = {}) {
+  const markdown = typeof item === 'string' ? item : String(item?.markdown ?? item?.content ?? '');
+  if (!markdown) return;
+  const parsed = parseArtifactMarkdown(markdown);
+  const schemaId = String(item?.schemaId || parsed.envelope?.current?.schema?.id || '').trim();
+  if (!schemaId || out.has(schemaId)) return;
+  out.set(schemaId, markdown);
+}
+
+function artifactIdentity(record = {}) {
+  const declaredSchemaId = declaredRecordSchemaId(record);
+  const metadataSchemaId = recordSchemaId(record);
+  const workspaceIds = Array.isArray(record.workspaceIds)
+    ? [...new Set(record.workspaceIds.map((value) => String(value || '').trim()).filter(Boolean))].sort()
+    : String(record.workspaceId || '').trim() ? [String(record.workspaceId).trim()] : [];
+  const registryIdentity = record.registryIdentity || registryIdentityForRecord(record, workspaceIds, declaredRecordSchemaId, recordSchemaId);
+  return Object.freeze({
+    id: String(record.id || ''),
+    registryIdentity: String(registryIdentity.id || ''),
+    registryIdentityKind: String(registryIdentity.kind || ''),
+    loadedRecordIds: Object.freeze([...(record.loadedRecordIds || [record.id]).map((value) => String(value || '').trim()).filter(Boolean)].sort()),
+    workspaceId: workspaceIds[0] || '',
+    workspaceIds: Object.freeze(workspaceIds),
+    path: String(record.path || ''),
+    schemaId: declaredSchemaId || metadataSchemaId,
+    metadataSchemaId,
+    createdAt: String(record.currentCreatedAt || record.createdAt || '')
+  });
+}
+
+function sourceIdentity(record = {}) {
+  const source = record.source || {};
+  const identity = record.registryIdentity || registryIdentityForRecord(record, record.workspaceIds || [], declaredRecordSchemaId, recordSchemaId);
+  if (identity.kind === 'configured-source') {
+    const boundary = identity.sourceBoundary || sourceBoundaryIdentity(record) || {};
+    const repository = String(boundary.repository || '');
+    const ref = String(boundary.ref || '');
+    const rootPath = String(boundary.rootPath || '');
+    return Object.freeze({
+      sourceId: String(globalThis.TiinexSourceIdentity?.makeConfiguredSourceId?.({ repository, ref, rootPath }) || ''),
+      loadedSourceIds: Object.freeze([...(record.loadedSourceIds || [])]),
+      adapterId: String(source.adapterId || 'github'),
+      sourceMode: String(record.sourceMode || ''),
+      repository,
+      ref,
+      rootPath,
+      boundaryKey: String(boundary.key || identity.boundaryKey || ''),
+      boundarySignature: String(boundary.signature || identity.boundarySignature || ''),
+      sourceArtifactPath: String(identity.sourceArtifactPath || ''),
+      inputTarget: ''
+    });
+  }
+  if (identity.kind === 'input-target') {
+    const loadedSourceIds = [...(record.loadedSourceIds || [])].map((value) => String(value || '').trim()).filter(Boolean).sort();
+    return Object.freeze({
+      sourceId: loadedSourceIds[0] || `input-target:${String(identity.inputTarget || '')}`,
+      loadedSourceIds: Object.freeze(loadedSourceIds),
+      adapterId: String(source.adapterId || ''),
+      sourceMode: String(record.sourceMode || ''),
+      repository: '',
+      ref: '',
+      rootPath: '',
+      boundaryKey: '',
+      boundarySignature: '',
+      sourceArtifactPath: '',
+      inputTarget: String(identity.inputTarget || '')
+    });
+  }
+  return Object.freeze({
+    sourceId: String(source.id || ''),
+    loadedSourceIds: Object.freeze([...(record.loadedSourceIds || [source.id]).map((value) => String(value || '').trim()).filter(Boolean)].sort()),
+    adapterId: String(source.adapterId || ''),
+    sourceMode: String(record.sourceMode || ''),
+    repository: String(source.repository || source.repo || source.config?.repo || ''),
+    ref: String(source.ref || source.requestedRef || source.config?.ref || ''),
+    rootPath: String(source.rootPath || source.config?.rootPath || ''),
+    boundaryKey: String(sourceBoundaryIdentity(record)?.key || ''),
+    boundarySignature: sourceBoundarySignature(record),
+    sourceArtifactPath: String(record.sourceTarget?.sourceArtifactPath || record.path || ''),
+    inputTarget: String(record.sourceTarget?.inputTarget || '')
+  });
+}
+
+function buildDiagnostics(chainQualification, validation, record = {}, schemaQualification = {}, ordinaryReadAuthority = {}) {
+  const diagnostics = [];
+  for (const message of chainQualification.findings || []) diagnostics.push(finding('schema-chain', message, chainQualification.state));
+  for (const item of validation.findings || []) diagnostics.push(Object.freeze({
+    source: 'compiled-contract-validation',
+    code: item.code || '',
+    severity: item.severity || '',
+    state: item.state || '',
+    message: item.message || '',
+    group: item.group || '',
+    entry: item.entry || '',
+    field: item.field || ''
+  }));
+  const declaredSchemaId = declaredRecordSchemaId(record);
+  const metadataSchemaId = recordSchemaId(record);
+  if (declaredSchemaId && metadataSchemaId && declaredSchemaId !== metadataSchemaId) {
+    diagnostics.push(Object.freeze({
+      source: 'transition-definition-registry',
+      code: 'canonical-transition.record-schema-metadata.drift',
+      severity: 'warning',
+      state: 'preserve',
+      message: `Artifact declares Current Schema ${declaredSchemaId} while record metadata reports ${metadataSchemaId}; canonical registry eligibility follows the artifact declaration.`
+    }));
+  }
+  if (schemaQualification.state === 'conflicting') {
+    diagnostics.push(Object.freeze({
+      source: 'transition-definition-registry',
+      code: 'canonical-transition.declared-schema.conflict',
+      severity: 'error',
+      state: 'contradictory',
+      message: `Loaded observations share one qualified source Artifact identity but declare divergent Current Schema values: ${(schemaQualification.declaredSchemaIds || []).join(', ')}.`
+    }));
+  } else if (schemaQualification.state === 'unresolved' && schemaQualification.canonicalObserved === true) {
+    diagnostics.push(Object.freeze({
+      source: 'transition-definition-registry',
+      code: 'canonical-transition.declared-schema.unresolved',
+      severity: 'warning',
+      state: 'unresolved',
+      message: 'At least one loaded observation declares the canonical Transition Definition schema while another observation has unreadable or unresolved Current Schema truth.'
+    }));
+  }
+  if (ordinaryReadAuthority.state === 'contradictory') {
+    diagnostics.push(Object.freeze({
+      source: 'transition-definition-registry',
+      code: 'canonical-transition.ordinary-read-authority.contradictory',
+      severity: 'error',
+      state: 'contradictory',
+      message: 'Compiled canonical schema chain has contradictory ordinary instance-read authority; canonical Transition Definition read qualification is refused.'
+    }));
+  } else if (ordinaryReadAuthority.state !== 'available') {
+    diagnostics.push(Object.freeze({
+      source: 'transition-definition-registry',
+      code: 'canonical-transition.ordinary-read-authority.unavailable',
+      severity: 'warning',
+      state: 'unresolved',
+      message: 'Compiled canonical schema chain does not provide usable ordinary instance-read authority; canonical Transition Definition read qualification is refused.'
+    }));
+  }
+  const aggregation = record.registryAggregation || {};
+  if (aggregation.representationState === 'conflicting') {
+    diagnostics.push(Object.freeze({
+      source: 'transition-definition-registry',
+      code: 'canonical-transition.representation.conflict',
+      severity: 'error',
+      state: 'contradictory',
+      message: 'Loaded observations share one qualified registry identity but contain divergent artifact representations; no canonical representation is selected for applicability or execution.'
+    }));
+  } else if (aggregation.representationState === 'unresolved') {
+    diagnostics.push(Object.freeze({
+      source: 'transition-definition-registry',
+      code: 'canonical-transition.representation.unresolved',
+      severity: 'warning',
+      state: 'unresolved',
+      message: 'Loaded observations share one qualified registry identity but upstream reconciliation does not prove one canonical representation.'
+    }));
+  }
+  return diagnostics;
+}
+
+function ordinaryReadAuthorityQualification(schemaChain = null) {
+  const authority = schemaChain?.validation?.ordinaryFieldAuthority;
+  const state = String(authority?.state || 'unavailable');
+  return Object.freeze({
+    state,
+    sources: Object.freeze([...(authority?.sources || [])]),
+    findings: Object.freeze([...(authority?.findings || [])])
+  });
+}
+
+function unresolvedQualification(message) {
+  return Object.freeze({ state: 'unresolved', complete: false, lineage: Object.freeze([]), findings: Object.freeze([message]) });
+}
+
+function unresolvedInstanceProjection() {
+  const validation = Object.freeze({
+    status: 'unresolved',
+    states: Object.freeze({ primary: 'unresolved', counts: Object.freeze({ valid: 0, incomplete: 0, unresolved: 1, preserve: 0, contradictory: 0, 'structurally-invalid': 0 }) }),
+    declarations: Object.freeze([]),
+    ordinaryGroups: Object.freeze([]),
+    findings: Object.freeze([Object.freeze({ severity: 'warning', code: 'canonical-transition.schema-contract.unavailable', state: 'unresolved', message: 'Canonical Transition Definition schema contract material is unavailable.' })])
+  });
+  return Object.freeze({ validation, ordinaryGroups: Object.freeze([]), declarations: Object.freeze([]) });
+}
+
+function finding(code, message, state) { return Object.freeze({ source: 'transition-definition-registry', code, severity: state === 'contradictory' ? 'error' : 'warning', state, message }); }
+function recordSchemaId(record = {}) { return schemaIdForRecord(record); }
+function declaredRecordSchemaId(record = {}) {
+  const markdown = String(record?.markdown || '');
+  if (!markdown) return '';
+  try { return String(parseArtifactMarkdown(markdown).envelope?.current?.schema?.id || '').trim(); }
+  catch { return ''; }
+}
+function compareReadModels(left, right) {
+  const canonical = String(left.transitionIdentity?.['Canonical Identifier'] || '').localeCompare(String(right.transitionIdentity?.['Canonical Identifier'] || ''));
+  if (canonical) return canonical;
+  const registryIdentity = String(left.artifact?.registryIdentity || '').localeCompare(String(right.artifact?.registryIdentity || ''));
+  if (registryIdentity) return registryIdentity;
+  return String(left.artifact?.path || left.artifact?.id || '').localeCompare(String(right.artifact?.path || right.artifact?.id || ''));
+}
+

package/src/transitions/transition.definitionRegistryAggregation.js

@@ -0,0 +1,21 @@
+import {
+  collectLoadedArtifactAggregates,
+  artifactRegistryIdentityForRecord,
+  readArtifactRepresentationQualification,
+  readArtifactSchemaQualification,
+  artifactSourceBoundaryIdentity,
+  artifactSourceBoundarySignature
+} from '../artifacts/artifact.identityAggregation.js';
+
+const TRANSITION_REGISTRY_IDENTITY_PREFIX = 'tiinex.transition.registry';
+
+export function collectTransitionDefinitionRegistryRecords(input = {}, declaredSchemaIdForRecord = () => '', metadataSchemaIdForRecord = () => '', canonicalSchemaId = '') {
+  return collectLoadedArtifactAggregates(input, declaredSchemaIdForRecord, metadataSchemaIdForRecord, canonicalSchemaId, TRANSITION_REGISTRY_IDENTITY_PREFIX);
+}
+export function registryIdentityForRecord(record = {}, workspaceIds = [], declaredSchemaIdForRecord = () => '', metadataSchemaIdForRecord = () => '') {
+  return artifactRegistryIdentityForRecord(record, workspaceIds, declaredSchemaIdForRecord, metadataSchemaIdForRecord, TRANSITION_REGISTRY_IDENTITY_PREFIX);
+}
+export function readTransitionDefinitionRepresentationQualification(...args) { return readArtifactRepresentationQualification(...args); }
+export function readTransitionDefinitionSchemaQualification(...args) { return readArtifactSchemaQualification(...args); }
+export function sourceBoundaryIdentity(...args) { return artifactSourceBoundaryIdentity(...args); }
+export function sourceBoundarySignature(...args) { return artifactSourceBoundarySignature(...args); }

package/src/transitions/transition.definitions.js

@@ -0,0 +1,46 @@
+import { companionForRecord } from '@tiinex/core/schemas/companion.js';
+import {
+  LEGACY_TRANSITION_SHORTHAND_CONTRACT_ID,
+  LEGACY_TRANSITION_INTENTS,
+  LEGACY_TRANSITION_PRESENTATION_VARIANTS,
+  LEGACY_TRANSITION_ICON_TOKENS,
+  normalizeLegacyTransitionDefinition,
+  validateLegacyTransitionDefinitions
+} from './transition.legacyShorthand.js';
+
+// Backward-compatible exports for the frozen v404 consumer API. The emitted
+// objects are explicitly site-local legacy shorthand, not canonical S1
+// tiinex.transition.definition.v1 instances.
+export const TRANSITION_DEFINITION_CONTRACT_ID = LEGACY_TRANSITION_SHORTHAND_CONTRACT_ID;
+export const TRANSITION_INTENTS = LEGACY_TRANSITION_INTENTS;
+export const TRANSITION_PRESENTATION_VARIANTS = LEGACY_TRANSITION_PRESENTATION_VARIANTS;
+export const TRANSITION_ICON_TOKENS = LEGACY_TRANSITION_ICON_TOKENS;
+
+export function transitionDefinitionsForRecord(record = {}, options = {}) {
+  const companion = companionForRecord(record);
+  return transitionDefinitionsForSchemaModule(companion, options).filter((definition) => transitionAvailableForRecord(definition, record));
+}
+
+export function transitionDefinitionsForSchemaModule(module = {}, options = {}) {
+  const raw = typeof module?.transitions === 'function' ? module.transitions(options) : module?.transitions;
+  const items = Array.isArray(raw) ? raw : Object.values(raw || {});
+  return items
+    .map((item) => normalizeLegacyTransitionDefinition(item, module))
+    .filter((definition) => definition.status === 'active')
+    .sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id));
+}
+
+export const normalizeTransitionDefinition = normalizeLegacyTransitionDefinition;
+export const validateTransitionDefinitions = validateLegacyTransitionDefinitions;
+
+function transitionAvailableForRecord(definition = {}, record = {}) {
+  const sourceMode = String(record.sourceMode || '').trim();
+  const sourceBacked = sourceMode === 'source-backed' || record.source?.adapterId === 'github';
+  const sourceModes = definition.availability?.sourceModes || [];
+  if (!sourceModes.length) return true;
+  return sourceModes.some((mode) => {
+    if (mode === 'source-backed') return sourceBacked;
+    if (mode === 'local-*') return sourceMode.startsWith('local') || record.source?.adapterId === 'local';
+    return mode === sourceMode;
+  });
+}

package/src/transitions/transition.explicitGenerationPlanner.js

@@ -0,0 +1,58 @@
+import { hasConcreteInvocationValue, immutableInvocationValue } from './transition.invocationBindingPacket.js';
+
+const freeze = Object.freeze;
+const NONE = freeze([]);
+
+export function planExplicitGeneration({ role = {}, declared = '', generationInputs = [], explicitAuthorities = [] } = {}) {
+  const targetSchema = token(role.schemaConstraint);
+  if (!targetSchema || role.schemaConstraintQualification !== 'resolved') return generationPlan(declared, 'unresolved', 'explicit-generation-target-schema-unresolved');
+  if (explicitAuthorities.length > 1) return generationPlan(declared, 'invalid', 'duplicate-explicit-generation-authority-entry');
+  if (!explicitAuthorities.length) return generationPlan(declared, 'unresolved', 'explicit-generation-authority-missing');
+  const qualification = explicitAuthorities[0]?.qualification || {};
+  const state = token(qualification.qualification);
+  if (state !== 'qualified') {
+    const mapped = state === 'invalid' || state === 'ambiguous' ? 'invalid' : state === 'incomplete' ? 'incomplete' : 'unresolved';
+    return generationPlan(declared, mapped, `explicit-generation-authority-${state || 'unresolved'}`);
+  }
+  if (token(qualification.outputRoleName) !== token(role.name)) return generationPlan(declared, 'invalid', 'explicit-generation-output-role-mismatch');
+  if (token(qualification.declaredBinding) !== declared) return generationPlan(declared, 'invalid', 'explicit-generation-binding-mismatch');
+  if (token(qualification.expectedTargetSchema) !== targetSchema) return generationPlan(declared, 'invalid', 'explicit-generation-expected-target-schema-mismatch');
+  if (token(qualification.authority?.generationTargetSchema) !== targetSchema) return generationPlan(declared, 'invalid', 'explicit-generation-authority-target-schema-mismatch');
+  if (token(qualification.authority?.authoritySchemaId) !== 'tiinex.schema.generation.v1') return generationPlan(declared, 'invalid', 'explicit-generation-authority-schema-mismatch');
+  if (qualification.resolution?.qualification !== 'resolved' || (qualification.resolution?.candidates || []).length !== 1) return generationPlan(declared, 'invalid', 'explicit-generation-resolution-not-exact');
+  const selected = qualification.authority?.selectedRepresentation || null;
+  const resolved = qualification.resolution.candidates[0] || null;
+  if (!selected || stableJson(selected) !== stableJson(resolved)) return generationPlan(declared, 'invalid', 'explicit-generation-authority-source-mismatch');
+  if (!qualification.declaringRepresentation?.representationKey || !qualification.declaringRepresentation?.path) return generationPlan(declared, 'invalid', 'explicit-generation-declaring-source-unresolved');
+  const requiredInputs = freeze((qualification.authority?.requiredInputs || []).map((item) => token(item?.name)).filter(Boolean));
+  if (!requiredInputs.length) return generationPlan(declared, 'incomplete', 'explicit-generation-required-input-surface-missing');
+  const inputs = planInputs(requiredInputs, generationInputs);
+  return freeze({
+    declared, authority: 'explicit-reference', reference: declared, state: inputs.state, reason: inputs.reason,
+    compiledSchemaId: targetSchema, lineageQualification: null, requiredInputs, optionalInputs: NONE, requiredSections: NONE,
+    toolingConfigurationFields: NONE, creationGroups: NONE, inputPlans: inputs.plans, unclaimedInputs: inputs.unclaimed,
+    explicitQualification: freeze({ qualification: state, declaringRepresentation: qualification.declaringRepresentation, selectedRepresentation: selected, generationIdentity: qualification.authority?.generationIdentity || null, targetOutput: qualification.authority?.targetOutput || '', outputBoundary: qualification.authority?.outputBoundary || null, interpretationLimits: qualification.authority?.interpretationLimits || null, generationSteps: qualification.authority?.generationSteps || NONE }),
+    draftRendered: false, executable: false
+  });
+}
+
+function planInputs(requiredInputs, entries) {
+  const required = new Set(requiredInputs);
+  const plans = [];
+  let state = 'resolved', reason = '';
+  for (const name of required) {
+    const matches = entries.filter((entry) => entry.name === name);
+    let inputState = 'resolved', inputReason = '';
+    if (matches.length > 1) { inputState = 'invalid'; inputReason = 'duplicate-generation-input'; }
+    else if (!matches.length || !hasConcreteInvocationValue(matches[0])) { inputState = 'incomplete'; inputReason = 'required-generation-input-missing'; }
+    state = stronger(state, inputState);
+    if (!reason && inputState !== 'resolved') reason = inputReason;
+    plans.push(freeze({ name, required: true, state: inputState, reason: inputReason, value: matches[0] && hasConcreteInvocationValue(matches[0]) ? immutableInvocationValue(matches[0].value) : undefined }));
+  }
+  const unclaimed = entries.filter((entry) => !required.has(entry.name)).map((entry) => freeze({ name: entry.name, hasValue: hasConcreteInvocationValue(entry), value: hasConcreteInvocationValue(entry) ? immutableInvocationValue(entry.value) : undefined, category: 'unclaimed-extra' }));
+  return freeze({ state, reason, plans: freeze(plans), unclaimed: freeze(unclaimed) });
+}
+function generationPlan(declared, state, reason) { return freeze({ declared, authority: 'explicit-reference', reference: declared, state, reason, compiledSchemaId: '', lineageQualification: null, requiredInputs: NONE, optionalInputs: NONE, requiredSections: NONE, toolingConfigurationFields: NONE, creationGroups: NONE, inputPlans: NONE, unclaimedInputs: NONE, draftRendered: false, executable: false }); }
+function stronger(a, b) { const order = ['invalid', 'unresolved', 'incomplete', 'resolved']; return order.indexOf(a) <= order.indexOf(b) ? a : b; }
+function stableJson(value) { return JSON.stringify(value ?? null); }
+function token(value = '') { return String(value || '').trim(); }

package/src/transitions/transition.generationInputPlanner.js

@@ -0,0 +1,19 @@
+import { immutableInvocationValue } from './transition.invocationBindingPacket.js';
+const freeze = Object.freeze;
+export function planGenerationInputs(outputRole, creation = {}, entries = []) {
+  const required = new Set(creation.requiredInputs || []), optional = new Set(creation.optionalInputs || []), tooling = new Set(creation.toolingConfigurationFields || []);
+  const declared = new Set([...required, ...optional]), plans = [];
+  let state = 'resolved', reasonCode = '';
+  for (const name of declared) {
+    const matches = entries.filter((entry) => entry.name === name);
+    let inputState = 'resolved', reason = '';
+    if (matches.length > 1) { inputState = 'invalid'; reason = 'duplicate-generation-input'; }
+    else if (!matches.length || !matches[0].hasValue) { inputState = required.has(name) ? 'incomplete' : 'optional-unbound'; reason = required.has(name) ? 'required-generation-input-missing' : 'optional-generation-input-unbound'; }
+    state = stronger(state, inputState);
+    if (!reasonCode && ['invalid', 'unresolved', 'incomplete'].includes(inputState)) reasonCode = reason;
+    plans.push(freeze({ name, required: required.has(name), state: inputState, reason, value: matches[0]?.hasValue ? immutableInvocationValue(matches[0].value) : undefined }));
+  }
+  const unclaimed = entries.filter((entry) => !declared.has(entry.name)).map((entry) => freeze({ name: entry.name, hasValue: entry.hasValue, value: entry.hasValue ? immutableInvocationValue(entry.value) : undefined, category: tooling.has(entry.name) ? 'tooling-configuration' : 'unclaimed-extra' }));
+  return freeze({ state, reason: reasonCode, plans: freeze(plans), unclaimed: freeze(unclaimed), outputRole });
+}
+function stronger(left, right) { const normalize = (s) => ['resolved', 'optional-unbound'].includes(s) ? 'qualified' : s; const order = ['invalid','unresolved','incomplete','qualified']; const a=normalize(left), b=normalize(right); return order.indexOf(a) <= order.indexOf(b) ? (a === 'qualified' ? 'resolved' : a) : (b === 'qualified' ? 'resolved' : b); }

package/src/transitions/transition.interpretationMaterializer.js

@@ -0,0 +1,2 @@
+// Compatibility re-export. Schema-specific representation ownership lives with the schema companion.
+export * from '@tiinex/core/schemas/core/interpretation/tiinex.interpretation.v1.localMaterialization.js';

package/src/transitions/transition.invocationBindingPacket.js

@@ -0,0 +1,52 @@
+export function normalizeInvocationBindingPacket(packet = {}) {
+  return Object.freeze({
+    inputRoles: Object.freeze(asArray(packet.inputRoles).map((entry) => Object.freeze({
+      role: token(entry?.role),
+      members: Object.freeze(asArray(entry?.members).map((member) => Object.freeze({ ...member })))
+    }))),
+    destinations: Object.freeze(asArray(packet.destinations).map((entry) => Object.freeze({
+      name: token(entry?.name),
+      hasValue: hasConcreteInvocationValue(entry),
+      value: entry?.value
+    }))),
+    naming: Object.freeze(asArray(packet.naming).map((entry) => Object.freeze({
+      placement: token(entry?.placement),
+      hasValue: hasConcreteInvocationValue(entry),
+      value: entry?.value
+    }))),
+    memberAssociations: Object.freeze(asArray(packet.memberAssociations).map((entry) => Object.freeze({
+      group: token(entry?.group),
+      effect: token(entry?.effect),
+      associations: Object.freeze(asArray(entry?.associations).map((association) => Object.freeze({
+        from: Object.freeze({ ...(association?.from || {}) }),
+        to: Object.freeze({ ...(association?.to || {}) })
+      })))
+    })))
+  });
+}
+
+export function hasConcreteInvocationValue(entry) {
+  return Object.prototype.hasOwnProperty.call(entry || {}, 'value') && entry?.value !== undefined;
+}
+
+export function invocationBindingPacketCounts(packet) {
+  return Object.freeze({
+    inputRoleEntries: packet.inputRoles.length,
+    destinationEntries: packet.destinations.length,
+    namingEntries: packet.naming.length,
+    memberAssociationEntries: packet.memberAssociations.length
+  });
+}
+
+export function immutableInvocationValue(value) {
+  if (value === undefined || value === null || typeof value !== 'object') return value;
+  return deepFreeze(structuredClone(value));
+}
+
+function asArray(value) { return Array.isArray(value) ? value : []; }
+function token(value = '') { return String(value || '').trim(); }
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const key of Reflect.ownKeys(value)) deepFreeze(value[key]);
+  return Object.freeze(value);
+}