@tiinex/app 0.1.1

package/src/transitions/transition.localCreateCapability.js

@@ -0,0 +1,111 @@
+export const CANONICAL_LOCAL_CREATE_CAPABILITY_OWNER_SCHEMA_ID = 'tiinex.site.canonical-local-create-capability-owner.v1';
+const freeze = Object.freeze;
+
+export function localCreateCapability(input = {}) {
+  return input.productScope === 'workspace' ? workspaceRootCreateCapability(input) : recordLocalCreateCapability(input);
+}
+
+function recordLocalCreateCapability({ result, availability, creation, currentParticipant, workspaceId, parent, materializer }) {
+  const reasons = [];
+  const outputs = result.outputRoles || [];
+  const output = outputs[0];
+  const lifecycle = result.lifecycleEffects || [];
+  const parents = result.parentEffects || [];
+  const relations = result.relationEffects || [];
+  const placements = result.outputPlacements || [];
+  const destinations = result.destinationBindings || [];
+  const parentEffect = parents[0];
+  const parentRoleName = token(parentEffect?.parentBinding?.resolvedName);
+  const currentRoleIds = availability.context?.candidateRoleIds || [];
+  const parentRole = (availability.inputRoles || []).find((role) => role.name === parentRoleName);
+  const inputSchemaId = token(parentRole?.schemaConstraint);
+  const outputSchemaId = token(output?.schemaConstraint);
+
+  if (availability.availability !== 'available') reasons.push('canonical-transition-not-available');
+  if (result.qualification !== 'qualified') reasons.push('canonical-result-semantics-not-qualified');
+  if (availability.context?.assignment !== 'unique' || !currentParticipant) reasons.push('current-artifact-role-not-unique');
+  if ((availability.inputRoles || []).length !== 1) reasons.push('unsupported-input-role-arity');
+  if (outputs.length !== 1) reasons.push('unsupported-output-role-arity');
+  if (currentRoleIds.length !== 1 || !parentRoleName || parentRoleName !== currentRoleIds[0]) reasons.push('parent-role-not-current-artifact-role');
+  if (!supportedCanonicalParentRole(parentRole)) reasons.push('unsupported-parent-role-capability');
+  if (currentParticipant?.cleanCandidate !== true || !inputSchemaId || currentParticipant?.candidateSchemaId !== inputSchemaId) reasons.push('current-artifact-schema-unqualified');
+  if (!supportedCanonicalOutput(output)) reasons.push('unsupported-output-capability');
+  if (lifecycle.length !== 1 || !supportedLifecycle(lifecycle[0], output)) reasons.push('unsupported-lifecycle-capability');
+  if (parents.length !== 1 || !supportedParentEffect(parentEffect, output, parentRoleName)) reasons.push('unsupported-parent-capability');
+  if (relations.length) reasons.push('relation-effects-not-supported');
+  if (!supportedLocalPlacement(placements, destinations, output)) reasons.push('unsupported-placement-capability');
+  if (creation.state !== 'qualified' || creation.schemaId !== outputSchemaId) reasons.push('creation-authority-unavailable');
+  if (!materializer || materializer.schemaId !== outputSchemaId) reasons.push('local-materializer-unavailable');
+  if (!String(workspaceId || '').trim()) reasons.push('workspace-destination-unavailable');
+  if (parent.state !== 'qualified' || !inputSchemaId || parent.schemaId !== inputSchemaId) reasons.push(parent.reason || 'parent-recovery-unavailable');
+  const uniqueReasons = unique(reasons);
+  return freeze({ state: uniqueReasons.length ? 'unavailable' : 'qualified', reasons: freeze(uniqueReasons), remoteWrite: false, sourceMutation: false, relationMaterialization: false, concretePath: null, executablePattern: uniqueReasons.length === 0, scope: 'record', continuityMode: 'parent' });
+}
+
+function workspaceRootCreateCapability({ result, availability, creation, workspaceId, materializer }) {
+  const reasons = [];
+  const outputs = result.outputRoles || [];
+  const output = outputs[0];
+  const lifecycle = result.lifecycleEffects || [];
+  const parents = result.parentEffects || [];
+  const relations = result.relationEffects || [];
+  const placements = result.outputPlacements || [];
+  const destinations = result.destinationBindings || [];
+  const outputSchemaId = token(output?.schemaConstraint);
+  if (availability.availability !== 'available') reasons.push('canonical-transition-not-available');
+  if (result.qualification !== 'qualified') reasons.push('canonical-result-semantics-not-qualified');
+  if ((availability.inputRoles || []).length !== 0) reasons.push('root-create-requires-zero-input-roles');
+  if (availability.context?.assignment !== 'none' || availability.context?.provided === true) reasons.push('root-create-current-artifact-context-not-empty');
+  if (outputs.length !== 1) reasons.push('unsupported-output-role-arity');
+  if (!supportedCanonicalOutput(output)) reasons.push('unsupported-output-capability');
+  if (lifecycle.length !== 1 || !supportedLifecycle(lifecycle[0], output)) reasons.push('unsupported-lifecycle-capability');
+  if (parents.length !== 0) reasons.push('root-create-parent-effect-not-allowed');
+  if (relations.length !== 0) reasons.push('relation-effects-not-supported');
+  if (!supportedLocalPlacement(placements, destinations, output)) reasons.push('unsupported-placement-capability');
+  if (creation.state !== 'qualified' || creation.schemaId !== outputSchemaId) reasons.push('creation-authority-unavailable');
+  if (!materializer || materializer.schemaId !== outputSchemaId) reasons.push('root-local-materializer-unavailable');
+  if (!String(workspaceId || '').trim()) reasons.push('workspace-destination-unavailable');
+  const uniqueReasons = unique(reasons);
+  return freeze({ state: uniqueReasons.length ? 'unavailable' : 'qualified', reasons: freeze(uniqueReasons), remoteWrite: false, sourceMutation: false, relationMaterialization: false, concretePath: null, executablePattern: uniqueReasons.length === 0, scope: 'workspace', continuityMode: 'root' });
+}
+
+function supportedLifecycle(effect = {}, output = {}) {
+  const mapping = token(effect.memberMapping?.declared);
+  return effect.participation?.state === 'active' && effect.targetBinding?.resolvedName === output?.name
+    && effect.effect === 'create-new' && effect.logicalContinuity === 'new-subject' && effect.requiredMaterializationOperation === 'create'
+    && effect.resultBinding?.qualification === 'absent' && !token(effect.resultBinding?.declared)
+    && ['', 'no'].includes(token(effect.preserveWhy)) && ['', 'single'].includes(mapping);
+}
+function supportedParentEffect(effect = {}, output = {}, parentRoleName = '') {
+  return effect.participation?.state === 'active' && effect.effect === 'set' && effect.outputBinding?.resolvedName === output?.name
+    && Boolean(parentRoleName) && ['', 'single'].includes(token(effect.memberMapping?.declared));
+}
+function supportedCanonicalParentRole(role = {}) {
+  return role.targetKind === 'artifact' && role.effectiveParticipantKind === 'artifact' && Boolean(token(role.schemaConstraint))
+    && exactNumericCardinality(role.cardinality?.minimum, 1) && exactNumericCardinality(role.cardinality?.maximum, 1)
+    && role.acquisitionPolicy === 'existing-only';
+}
+function supportedCanonicalOutput(role = {}) {
+  return role.targetKind === 'artifact' && role.effectiveParticipantKind === 'artifact' && Boolean(token(role.schemaConstraint))
+    && exactNumericCardinality(role.minimumCount, 1) && exactNumericCardinality(role.maximumCount, 1)
+    && role.generationBinding === 'target-schema';
+}
+function supportedLocalPlacement(placements = [], destinations = [], output = {}) {
+  const placement = placements[0];
+  const destination = destinations[0];
+  const destinationFields = destination?.fields || {};
+  return placements.length === 1 && destinations.length === 1
+    && placement?.outputBinding?.resolvedName === output?.name
+    && placement?.destinationBinding?.resolvedName === destination?.name
+    && !token(placement?.relativeToBinding?.declared) && !placement?.relativeToBinding?.resolvedName
+    && !token(placement?.relativePlacementMeaning) && !token(placement?.namingAuthorityReference)
+    && placement?.placementIntent === 'new-materialization'
+    && placement?.namingAuthority === 'explicit-binding'
+    && placement?.explicitOverrideAllowed === 'no'
+    && destination?.requiredQualification?.state === 'required'
+    && !token(destinationFields['Destination Kind']) && !token(destinationFields['Capability Requirement']);
+}
+function exactNumericCardinality(value = {}, expected = 1) { return value.kind === 'numeric' && value.value === expected; }
+
+function token(value = '') { return String(value || '').trim(); }
+function unique(values = []) { return [...new Set(values.filter(Boolean))]; }

package/src/transitions/transition.outputMaterializationPlanner.js

@@ -0,0 +1,336 @@
+import { compilePortableSchemaContractChain } from '@tiinex/core/tooling/portable/schema/contract.compile.js';
+import { buildCanonicalTransitionInvocationBindingPlan } from './transition.invocationBindingPlanner.js';
+import { buildCanonicalTransitionResultPlan } from './transition.resultSemantics.js';
+import { hasConcreteInvocationValue, immutableInvocationValue } from './transition.invocationBindingPacket.js';
+import { planExplicitGeneration } from './transition.explicitGenerationPlanner.js';
+import { planGenerationInputs } from './transition.generationInputPlanner.js';
+export const TRANSITION_OUTPUT_MATERIALIZATION_PLAN_SCHEMA_ID = 'tiinex.site.transition-output-materialization-intent-plan.v1';
+const freeze = Object.freeze;
+const NONE = freeze([]);
+const LOCAL_ORDER = freeze(['invalid', 'unresolved', 'incomplete', 'qualified']);
+const PLAN_BOUNDARY = freeze({ readOnly: true, mutation: false, networkFetch: false, artifactCreated: false, draftRendered: false, pathResolution: false, materialization: false, parentMutation: false, relationMaterialization: false, execution: false, executable: false });
+export function buildCanonicalTransitionOutputMaterializationPlan(input = {}) {
+  const definition = input.definition || {};
+  const bindingPlan = buildCanonicalTransitionInvocationBindingPlan({
+    definition,
+    participantIndex: input.participantIndex,
+    currentArtifact: input.currentArtifact,
+    bindingPacket: input.bindingPacket
+  });
+  const result = buildCanonicalTransitionResultPlan({ definition });
+  const generationInputs = normalizeGenerationInputs(input.generationInputs);
+  const authorities = normalizeTargetAuthorities(input.targetSchemaAuthorities);
+  const explicitAuthorities = normalizeExplicitGenerationAuthorities(input.explicitGenerationAuthorities);
+  if (bindingPlan.qualification !== 'qualified') {
+    return upstreamPlan(bindingPlan, result, generationInputs, authorities, explicitAuthorities);
+  }
+  const outputs = result.outputRoles || [];
+  const outputNames = new Set(outputs.map((role) => role.name));
+  const targetSchemas = new Set(outputs.filter((role) => role.generationBinding === 'target-schema').map((role) => role.name));
+  const generationAudit = auditGenerationNamespaces(generationInputs, authorities, explicitAuthorities, outputNames, targetSchemas);
+  const outputRolePlans = (result.outputRoles || []).map((role) => planOutputRole({
+    role,
+    result,
+    bindingPlan,
+    generationInputs: generationInputs.filter((entry) => entry.outputRole === role.name),
+    authorities: authorities.filter((entry) => entry.outputRole === role.name),
+    explicitAuthorities: explicitAuthorities.filter((entry) => entry.outputRole === role.name)
+  }));
+  const localReasons = collectLocalReasons(generationAudit, outputRolePlans);
+  const qualification = dominantLocalQualification(localReasons);
+  return freeze({
+    schema: TRANSITION_OUTPUT_MATERIALIZATION_PLAN_SCHEMA_ID,
+    definition: freeze({ ...(bindingPlan.definition || {}) }),
+    qualification,
+    reasons: freeze(flattenReasonBuckets(localReasons)),
+    reasonsByState: localReasons,
+    bindingPlan: bindingSummary(bindingPlan),
+    resultSemantics: resultSummary(result),
+    generationAudit,
+    outputRolePlans: freeze(outputRolePlans),
+    ...PLAN_BOUNDARY
+  });
+}
+function planOutputRole({ role, result, bindingPlan, generationInputs, authorities, explicitAuthorities }) {
+  const count = outputCount(role);
+  const zero = count.state === 'resolved' && count.exactCount === 0;
+  const targetKind = role.effectiveParticipantKind || '';
+  const declaredGeneration = role.generationBinding || '';
+  const generation = zero
+    ? generationPlan(declaredGeneration, 'not-required', 'exact-zero-output-no-generation-obligation', declaredGeneration === 'target-schema'
+      ? { authority: 'target-schema' } : declaredGeneration ? { authority: 'explicit-reference', reference: declaredGeneration } : { authority: 'not-prescribed' })
+    : planGeneration({ role, targetKind, generationInputs, authorities, explicitAuthorities });
+  const lifecycleBase = planLifecycle(role, result);
+  const lifecycle = zero ? freeze({ ...lifecycleBase, state: 'not-required', reason: 'exact-zero-output-no-materialization-obligation', requestedOperation: '', command: null }) : lifecycleBase;
+  const placements = (result.outputPlacements || []).filter((placement) => placement.outputBinding?.resolvedName === role.name).map((placement) => zero
+    ? placementPlan(placement, 'not-required', 'exact-zero-output-no-placement-obligation', undefined, noNaming(planNaming(placement, bindingPlan), 'exact-zero-output-no-naming-obligation'))
+    : planPlacement(placement, bindingPlan));
+  const mappingDependencies = planMappingDependencies(role, result, bindingPlan).map((mapping) => zero
+    ? freeze({ ...mapping, sourceState: mapping.state, state: 'not-required', reason: 'exact-zero-output-no-mapping-obligation', associations: NONE, positionalInference: false }) : mapping);
+  const parentDependencies = (result.parentEffects || []).filter((effect) => effect.outputBinding?.resolvedName === role.name)
+    .map((effect) => freeze({ effect: effect.name, state: zero ? 'not-required' : 'deferred', actualParentAssigned: false }));
+  const relationDependencies = (result.relationEffects || [])
+    .filter((effect) => effect.subjectBinding?.resolvedName === role.name || effect.objectBinding?.resolvedName === role.name)
+    .map((effect) => freeze({ effect: effect.name, state: zero ? 'not-required' : 'deferred', relationMaterialized: false }));
+  const reasons = [];
+  if (!zero) {
+    if (!targetKind) reasons.push(reason('unresolved', 'target-kind-unresolved'));
+    if (count.state !== 'resolved') reasons.push(reason('unresolved', 'output-count-unresolved'));
+    collectStateReason(reasons, 'generation', generation);
+    collectStateReason(reasons, 'lifecycle', lifecycle);
+    for (const placement of placements) collectStateReason(reasons, `placement:${placement.name}`, placement);
+    for (const mapping of mappingDependencies) if (['unresolved', 'invalid', 'incomplete'].includes(mapping.state)) {
+      reasons.push(reason(mapping.state, `mapping:${mapping.effect}:${mapping.reason || mapping.state}`));
+    }
+    if (targetKind === 'artifact' && ['create', 'revise'].includes(lifecycle.requestedOperation) && generation.authority === 'not-prescribed') {
+      reasons.push(reason('unresolved', 'generation-not-prescribed-for-materialization'));
+    }
+  }
+  return freeze({
+    name: role.name, targetKind: role.targetKind, effectiveParticipantKind: targetKind, participantClassification: role.participantClassification,
+    schemaConstraint: role.schemaConstraint, schemaConstraintQualification: role.schemaConstraintQualification, outputCount: count, generation, lifecycle,
+    placements: freeze(placements), mappingDependencies: freeze(mappingDependencies), parentDependencies: freeze(parentDependencies),
+    relationDependencies: freeze(relationDependencies), qualification: dominantReasonState(reasons),
+    reasons: freeze(reasons.map((item) => `${item.state}:${item.code}`)), outputMemberIds: NONE, artifactDraft: null, concretePath: null, executable: false
+  });
+}
+function outputCount(role) {
+  const minimum = role.minimumCount || {};
+  const maximum = role.maximumCount || {};
+  if (minimum.kind === 'numeric' && maximum.kind === 'numeric' && minimum.value === maximum.value) {
+    return freeze({ state: 'resolved', exactCount: minimum.value, minimum, maximum, memberIdentitiesInvented: false });
+  }
+  return freeze({ state: 'unresolved', exactCount: null, minimum, maximum, memberIdentitiesInvented: false });
+}
+function planGeneration({ role, targetKind, generationInputs, authorities, explicitAuthorities = [] }) {
+  const declared = role.generationBinding || '';
+  if (!targetKind) return generationPlan(declared, 'unresolved', 'participant-kind-unresolved');
+  if (targetKind === 'non-artifact') {
+    if (!declared) return generationPlan('', 'not-prescribed', 'generation-not-prescribed');
+    if (declared !== 'target-schema') return planExplicitGeneration({ role, declared, generationInputs, explicitAuthorities });
+    return generationPlan(declared, 'deferred', 'non-artifact-generation-runtime-not-owned', { authority: 'target-schema' });
+  }
+  if (targetKind !== 'artifact') return generationPlan(declared, 'unresolved', 'participant-kind-unresolved');
+  if (!declared) return generationPlan('', 'not-prescribed', 'generation-not-prescribed');
+  if (declared !== 'target-schema') return planExplicitGeneration({ role, declared, generationInputs, explicitAuthorities });
+  if (!role.schemaConstraint || role.schemaConstraintQualification !== 'resolved') {
+    return generationPlan(declared, 'unresolved', 'target-schema-constraint-unresolved', { authority: 'target-schema' });
+  }
+  if (authorities.length > 1) return generationPlan(declared, 'invalid', 'duplicate-target-schema-authority-entry', { authority: 'target-schema' });
+  if (!authorities.length) return generationPlan(declared, 'unresolved', 'target-schema-authority-missing', { authority: 'target-schema' });
+  const authority = authorities[0];
+  const readableMaterials = authority.materials.filter((material) => material.trim().length > 0);
+  if (!readableMaterials.length) return generationPlan(declared, 'unresolved', 'target-schema-authority-missing', { authority: 'target-schema' });
+  let compiled;
+  try { compiled = compilePortableSchemaContractChain(readableMaterials); }
+  catch { return generationPlan(declared, 'invalid', 'target-schema-authority-compile-failed', { authority: 'target-schema' }); }
+  if (compiled.schemaId !== role.schemaConstraint) {
+    return generationPlan(declared, 'invalid', 'target-schema-authority-schema-mismatch', { authority: 'target-schema', compiledSchemaId: compiled.schemaId });
+  }
+  if (compiled.lineageQualification?.state !== 'valid' || compiled.lineageQualification?.complete !== true) {
+    return generationPlan(declared, 'unresolved', 'target-schema-authority-lineage-unresolved', { authority: 'target-schema', compiledSchemaId: compiled.schemaId, lineageQualification: compiled.lineageQualification });
+  }
+  const creation = compiled.creation || {};
+  const usable = Boolean((creation.groups || []).length || (creation.requiredInputs || []).length || (creation.optionalInputs || []).length || (creation.requiredSections || []).length);
+  if (!usable) return generationPlan(declared, 'unresolved', 'target-schema-creation-authority-unavailable', { authority: 'target-schema', compiledSchemaId: compiled.schemaId });
+  const inputs = planGenerationInputs(role.name, creation, generationInputs);
+  return freeze({
+    declared,
+    authority: 'target-schema',
+    reference: '',
+    state: inputs.state,
+    reason: inputs.reason,
+    compiledSchemaId: compiled.schemaId,
+    lineageQualification: compiled.lineageQualification,
+    requiredInputs: freeze([...(creation.requiredInputs || [])]),
+    optionalInputs: freeze([...(creation.optionalInputs || [])]),
+    requiredSections: freeze([...(creation.requiredSections || [])]),
+    toolingConfigurationFields: freeze([...(creation.toolingConfigurationFields || [])]),
+    creationGroups: freeze((creation.groups || []).map((group) => group.name)),
+    inputPlans: inputs.plans,
+    unclaimedInputs: inputs.unclaimed,
+    draftRendered: false,
+    executable: false
+  });
+}
+
+function generationPlan(declared, state, reasonCode, extra = {}) {
+  return freeze({
+    declared,
+    authority: extra.authority || (declared ? 'unresolved' : 'not-prescribed'),
+    reference: extra.reference || '',
+    state,
+    reason: reasonCode,
+    compiledSchemaId: extra.compiledSchemaId || '',
+    lineageQualification: extra.lineageQualification || null,
+    requiredInputs: NONE,
+    optionalInputs: NONE,
+    requiredSections: NONE,
+    toolingConfigurationFields: NONE,
+    creationGroups: NONE,
+    inputPlans: NONE,
+    unclaimedInputs: NONE,
+    draftRendered: false,
+    executable: false
+  });
+}
+
+function planLifecycle(role, result) {
+  const active = (result.lifecycleEffects || []).filter((effect) =>
+    effect.participation?.state === 'active' && (effect.targetBinding?.resolvedName === role.name || effect.resultBinding?.resolvedName === role.name));
+  const effects = freeze(active.map((effect) => freeze({
+    name: effect.name, targetBinding: effect.targetBinding, resultBinding: effect.resultBinding, effect: effect.effect,
+    logicalContinuity: effect.logicalContinuity, requiredMaterializationOperation: effect.requiredMaterializationOperation || '',
+    memberMapping: effect.memberMapping?.declared || '', participation: effect.participation
+  })));
+  const operations = effects.filter((effect) => effect.requiredMaterializationOperation);
+  if (operations.length > 1) return freeze({ state: 'unresolved', reason: 'multiple-materialization-operations-require-composition', requestedOperation: '', effects, command: null });
+  if (operations.length === 1) return freeze({ state: 'resolved', reason: '', requestedOperation: operations[0].requiredMaterializationOperation, effects, command: null });
+  return freeze({ state: 'not-prescribed', reason: 'materialization-operation-not-prescribed', requestedOperation: '', effects, command: null });
+}
+
+function planPlacement(placement, bindingPlan) {
+  const intent = placement.placementIntent || '', naming = planNaming(placement, bindingPlan);
+  if (intent === 'no-materialization') return placementPlan(placement, 'resolved', 'physical-placement-not-required', undefined, noNaming(naming, 'physical-placement-not-required'));
+  const inactive = intent === 'unknown' ? 'placement-intent-unresolved' : intent === 'preserve-current' ? 'current-placement-authority-unavailable' : intent !== 'new-materialization' ? 'placement-intent-not-supported' : '';
+  if (inactive) return placementPlan(placement, 'unresolved', inactive, undefined, noNaming(naming, inactive));
+  const destinationName = placement.destinationBinding?.resolvedName || '';
+  const destination = (bindingPlan.destinationBindings || []).find((item) => item.name === destinationName);
+  if (!destinationName || !destination || destination.value === undefined) return placementPlan(placement, 'unresolved', 'destination-component-unresolved', undefined, naming);
+  if (placement.relativeToBinding?.resolvedName) return placementPlan(placement, 'unresolved', 'relative-placement-resolver-unavailable', destination.value, naming);
+  if (naming.state !== 'resolved' && naming.state !== 'not-required') return placementPlan(placement, naming.state, naming.reason, destination.value, naming);
+  return placementPlan(placement, 'resolved', '', destination.value, naming);
+}
+function noNaming(naming, reason) { return freeze({ ...naming, state: 'not-required', reason }); }
+
+function planNaming(placement, bindingPlan) {
+  const authority = placement.namingAuthority || '';
+  if (!authority) return freeze({ authority: '', state: 'unresolved', reason: 'naming-authority-not-prescribed', value: undefined });
+  if (authority === 'explicit-binding') {
+    const binding = (bindingPlan.namingBindings || []).find((item) => item.placement === placement.name);
+    if (binding?.state !== 'resolved' || binding.value === undefined) return freeze({ authority, state: 'incomplete', reason: 'explicit-naming-component-missing', value: undefined });
+    return freeze({ authority, state: 'resolved', reason: '', value: immutableInvocationValue(binding.value) });
+  }
+  if (authority === 'target-schema') return freeze({ authority, state: 'unresolved', reason: 'target-schema-naming-resolver-unavailable', value: undefined });
+  if (authority === 'external-authority') return freeze({ authority, state: 'unresolved', reason: 'external-naming-resolver-unavailable', reference: placement.namingAuthorityReference || '', value: undefined });
+  return freeze({ authority, state: 'unresolved', reason: 'naming-authority-unresolved', value: undefined });
+}
+
+function placementPlan(placement, state, reasonCode, destinationValue = undefined, naming = null) {
+  return freeze({
+    name: placement.name,
+    placementIntent: placement.placementIntent,
+    destinationBinding: placement.destinationBinding,
+    destinationValue: destinationValue === undefined ? undefined : immutableInvocationValue(destinationValue),
+    naming: naming || freeze({ authority: placement.namingAuthority || '', state: 'not-required', reason: '', value: undefined }),
+    relativeToBinding: placement.relativeToBinding,
+    relativePlacementMeaning: placement.relativePlacementMeaning,
+    explicitOverrideAllowed: placement.explicitOverrideAllowed,
+    state,
+    reason: reasonCode,
+    concretePath: null,
+    pathResolution: false,
+    materializationCommand: null,
+    executable: false
+  });
+}
+
+function planMappingDependencies(role, result, bindingPlan) {
+  const relevant = new Set();
+  for (const effect of result.lifecycleEffects || []) if (effect.targetBinding?.resolvedName === role.name || effect.resultBinding?.resolvedName === role.name) relevant.add(`lifecycle\u0000${effect.name}`);
+  for (const effect of result.parentEffects || []) if (effect.outputBinding?.resolvedName === role.name) relevant.add(`parent\u0000${effect.name}`);
+  for (const effect of result.relationEffects || []) if (effect.subjectBinding?.resolvedName === role.name || effect.objectBinding?.resolvedName === role.name) relevant.add(`relation\u0000${effect.name}`);
+  return (bindingPlan.memberAssociations || []).filter((item) => relevant.has(`${item.group}\u0000${item.effect}`)).map((item) => {
+    const declared = (result[`${item.group}Effects`] || []).find((effect) => effect.name === item.effect)?.memberMapping || {};
+    return freeze({ group: item.group, effect: item.effect, mapping: item.mapping, mappingKey: declared.mappingKey || '', mappingMeaning: declared.mappingMeaning || '', state: item.state, reason: item.reasons?.[0] || '', associations: freeze([...(item.associations || [])]), positionalInference: false });
+  });
+}
+
+function normalizeGenerationInputs(entries) {
+  return freeze((Array.isArray(entries) ? entries : []).map((entry) => freeze({
+    outputRole: token(entry?.outputRole),
+    name: token(entry?.name),
+    hasValue: hasConcreteInvocationValue(entry),
+    value: entry?.value
+  })));
+}
+function normalizeTargetAuthorities(entries) {
+  return freeze((Array.isArray(entries) ? entries : []).map((entry) => freeze({
+    outputRole: token(entry?.outputRole),
+    materials: freeze((Array.isArray(entry?.materials) ? entry.materials : []).map((item) => String(item || '')))
+  })));
+}
+function normalizeExplicitGenerationAuthorities(entries) {
+  return freeze((Array.isArray(entries) ? entries : []).map((entry) => freeze({
+    outputRole: token(entry?.outputRole),
+    qualification: entry?.qualification || entry?.projection || null
+  })));
+}
+
+function auditGenerationNamespaces(inputs, authorities, explicitAuthorities, outputNames, targetSchemas) {
+  const findings = [], keys = new Map();
+  for (const entry of inputs) {
+    if (!outputNames.has(entry.outputRole)) findings.push(freeze({ state: 'invalid', code: 'unknown-generation-output-role', subject: entry.outputRole }));
+    const key = `${entry.outputRole}\u0000${entry.name}`;
+    keys.set(key, (keys.get(key) || 0) + 1);
+  }
+  for (const [key, count] of keys) if (count > 1) findings.push(freeze({ state: 'invalid', code: 'duplicate-generation-input-entry', subject: key.replace('\u0000', ':') }));
+  for (const entry of authorities) {
+    if (!outputNames.has(entry.outputRole)) findings.push(freeze({ state: 'invalid', code: 'unknown-target-authority-output-role', subject: entry.outputRole }));
+  }
+  for (const entry of explicitAuthorities) {
+    if (!outputNames.has(entry.outputRole)) findings.push(freeze({ state: 'invalid', code: 'unknown-explicit-generation-output-role', subject: entry.outputRole }));
+  }
+  const explicitNames = new Set(explicitAuthorities.map((entry) => entry.outputRole));
+  for (const name of explicitNames) if (explicitAuthorities.filter((entry) => entry.outputRole === name).length > 1) findings.push(freeze({ state: 'invalid', code: 'duplicate-explicit-generation-authority-entry', subject: name }));
+  for (const name of targetSchemas) if (authorities.filter((entry) => entry.outputRole === name).length > 1) findings.push(freeze({ state: 'invalid', code: 'duplicate-target-schema-authority-entry', subject: name }));
+  return freeze({ findings: freeze(findings), generationInputEntries: inputs.length, targetAuthorityEntries: authorities.length, explicitAuthorityEntries: explicitAuthorities.length });
+}
+function collectLocalReasons(audit, outputPlans) {
+  const buckets = { invalid: [], unresolved: [], incomplete: [] };
+  for (const finding of audit.findings) buckets[finding.state].push(`${finding.code}:${finding.subject}`);
+  for (const output of outputPlans) for (const item of output.reasons) {
+    const split = item.indexOf(':');
+    const state = item.slice(0, split);
+    const code = item.slice(split + 1);
+    if (buckets[state]) buckets[state].push(`output:${output.name}:${code}`);
+  }
+  return freeze(Object.fromEntries(Object.entries(buckets).map(([state, values]) => [state, freeze(unique(values))])));
+}
+function collectStateReason(reasons, prefix, plan) {
+  if (['invalid', 'unresolved', 'incomplete'].includes(plan.state)) reasons.push(reason(plan.state, `${prefix}:${plan.reason || plan.state}`));
+}
+function reason(state, code) { return freeze({ state, code }); }
+function dominantReasonState(reasons) {
+  for (const state of LOCAL_ORDER) if (state === 'qualified' || reasons.some((item) => item.state === state)) return state;
+  return 'qualified';
+}
+function dominantLocalQualification(buckets) {
+  return LOCAL_ORDER.find((state) => state === 'qualified' || buckets[state]?.length) || 'qualified';
+}
+function strongerLocalState(left, right) {
+  const normalize = (state) => ['resolved', 'optional-unbound'].includes(state) ? 'qualified' : state;
+  const a = normalize(left); const b = normalize(right);
+  const order = ['invalid', 'unresolved', 'incomplete', 'qualified'];
+  return order.indexOf(a) <= order.indexOf(b) ? (a === 'qualified' ? 'resolved' : a) : (b === 'qualified' ? 'resolved' : b);
+}
+function upstreamPlan(bindingPlan, result, generationInputs, authorities, explicitAuthorities = []) {
+  return freeze({
+    schema: TRANSITION_OUTPUT_MATERIALIZATION_PLAN_SCHEMA_ID,
+    definition: freeze({ ...(bindingPlan.definition || {}) }),
+    qualification: bindingPlan.qualification,
+    reasons: freeze((bindingPlan.reasons || []).map((item) => `upstream:${item}`)),
+    reasonsByState: freeze({ upstream: freeze([...(bindingPlan.reasons || [])]) }),
+    bindingPlan: bindingSummary(bindingPlan),
+    resultSemantics: resultSummary(result),
+    generationAudit: freeze({ findings: NONE, generationInputEntries: generationInputs.length, targetAuthorityEntries: authorities.length, explicitAuthorityEntries: explicitAuthorities.length }),
+    outputRolePlans: NONE,
+    ...PLAN_BOUNDARY
+  });
+}
+function bindingSummary(plan) { return freeze({ qualification: plan.qualification, reasons: freeze([...(plan.reasons || [])]), executable: false }); }
+function resultSummary(plan) { return freeze({ qualification: plan.qualification, reasons: freeze([...(plan.reasons || [])]), executable: false }); }
+function flattenReasonBuckets(buckets) { return LOCAL_ORDER.filter((state) => state !== 'qualified').flatMap((state) => (buckets[state] || []).map((item) => `${state}:${item}`)); }
+function stableJson(value) { return JSON.stringify(value ?? null); }
+function token(value = '') { return String(value || '').trim(); }
+function unique(values) { return [...new Set(values.filter(Boolean))]; }

package/src/transitions/transition.parentReference.js

@@ -0,0 +1,90 @@
+import { externalWebArtifactUrl } from '@tiinex/core/sources/source.explicitTargets.js';
+
+const freeze = Object.freeze;
+
+export function recoverCanonicalParentReference(record = {}, participant = {}) {
+  const source = record.source || {};
+  const target = record.sourceTarget || {};
+  const snapshot = record.snapshot || {};
+  const adapterId = token(participant.source?.adapterId || source.adapterId);
+  const sourceMode = token(participant.source?.sourceMode || record.sourceMode);
+  const sourceKind = token(source.kind || source.sourceKind);
+  const targetKind = token(target.targetKind || snapshot.sourceKind);
+  const path = String(target.sourceArtifactPath || record.path || participant.source?.sourceArtifactPath || '').replace(/^\/+/, '');
+  const schemaId = token(participant.candidateSchemaId);
+  const localBoundary = adapterId === 'local' || /(^|[^a-z0-9])(local|session)([^a-z0-9]|$)/i.test(`${sourceMode} ${sourceKind}`);
+  const issueBoundary = /github-(issue|comment)-embedded/i.test(`${sourceMode} ${targetKind}`);
+
+  if (issueBoundary) {
+    const sourceUrl = token(target.inputTarget || snapshot.sourceUrl || record.recoveredFromUrl);
+    if (!path || !sourceUrl) return unavailableCanonicalParentReference('source-topic-social-parent-reference-unavailable');
+    const comment = /comment/i.test(`${sourceMode} ${targetKind}`) || /#issuecomment-/i.test(sourceUrl);
+    return freeze({ state: 'qualified', representationKind: comment ? 'github-comment-embedded' : 'github-issue-embedded', recoveryKind: comment ? 'github-comment-embedded' : 'github-issue-embedded', trace: path, traceTarget: path, origin: `[github ${comment ? 'comment' : 'issue'}](${sourceUrl})`, originTarget: sourceUrl, permalink: '', repository: '', ref: '', path, sourceUrl, schemaId, finalized: false });
+  }
+
+  const webUrl = externalWebArtifactUrl(record);
+  if (webUrl) {
+    const label = markdownLabel(record.title || participant.artifact?.title || 'Topic');
+    return freeze({ state: 'qualified', representationKind: 'web-markdown', recoveryKind: 'web-markdown', trace: `[${label}](${webUrl})`, traceTarget: webUrl, origin: `[web artifact](${webUrl})`, originTarget: webUrl, permalink: webUrl, repository: '', ref: '', path: '', sourceUrl: webUrl, schemaId, finalized: true });
+  }
+  const webDeclared = sourceMode === 'explicit-url' || targetKind === 'web.markdown' || sourceKind === 'web.markdown' || adapterId === 'web';
+  if (webDeclared) return unavailableCanonicalParentReference('source-topic-web-parent-reference-unavailable');
+
+  if (localBoundary && adapterId !== 'github') {
+    const localPath = String(record.path || '').replace(/^\/+/, '');
+    if (!localPath) return unavailableCanonicalParentReference('source-topic-local-parent-path-unavailable');
+    return freeze({ state: 'qualified', representationKind: 'local-path', recoveryKind: 'local-path', trace: localPath, traceTarget: localPath, origin: localPath, originTarget: localPath, permalink: '', repository: '', ref: '', path: localPath, sourceUrl: '', schemaId, finalized: false });
+  }
+
+  const repository = token(source.repository || source.repo || source.config?.repo);
+  const ref = exactCommit(target.materializedCommit) || exactCommit(source.materializedCommit) || exactCommit(participant.source?.materializedCommit)
+    || exactCommit(source.ref) || exactCommit(source.config?.ref) || exactCommit(participant.source?.ref);
+  if (adapterId !== 'github' || localBoundary || !repository || !ref || !path) return unavailableCanonicalParentReference();
+  const permalink = githubCommitPermalink(repository, ref, path);
+  if (!permalink) return unavailableCanonicalParentReference('source-topic-parent-link-target-unavailable');
+  const label = markdownLabel(record.title || participant.artifact?.title || 'Topic');
+  return freeze({ state: 'qualified', representationKind: 'github-repo-file', recoveryKind: 'github-repo-file', trace: `[${label}](${permalink})`, traceTarget: permalink, origin: `[browse + git](${permalink})`, originTarget: permalink, permalink, repository, ref, path, sourceUrl: permalink, schemaId, finalized: true });
+}
+
+export function finalizeCanonicalParentReference(parent = {}, childPath = '') {
+  if (parent.state !== 'qualified') return parent;
+  if (parent.representationKind === 'github-repo-file' || parent.representationKind === 'web-markdown') return parent.finalized ? parent : freeze({ ...parent, finalized: true });
+  const parentPath = String(parent.path || '').replace(/^\/+/, '');
+  const concreteChildPath = String(childPath || '').replace(/^\/+/, '');
+  if (!parentPath || !concreteChildPath) return unavailableCanonicalParentReference('canonical-parent-finalization-path-unavailable');
+  const traceTarget = relativeArtifactPath(concreteChildPath, parentPath) || parentPath;
+  const originTarget = parent.representationKind === 'local-path' ? parentPath : token(parent.sourceUrl || parent.originTarget);
+  if (!originTarget) return unavailableCanonicalParentReference('canonical-parent-origin-unavailable');
+  const origin = parent.representationKind === 'local-path' ? originTarget : `[github ${parent.representationKind === 'github-comment-embedded' ? 'comment' : 'issue'}](${originTarget})`;
+  return freeze({ ...parent, trace: traceTarget, traceTarget, origin, originTarget, finalized: true });
+}
+
+export function unavailableCanonicalParentReference(reason = 'source-topic-portable-parent-reference-unavailable') {
+  return freeze({ state: 'unavailable', trace: '', traceTarget: '', origin: '', originTarget: '', permalink: '', repository: '', ref: '', path: '', sourceUrl: '', schemaId: '', representationKind: '', recoveryKind: '', finalized: false, reason });
+}
+
+function githubCommitPermalink(repository, ref, path) {
+  try {
+    const repo = encodeGithubPath(repository);
+    const encodedPath = encodeGithubPath(path);
+    const target = repo && encodedPath ? `https://github.com/${repo}/blob/${ref}/${encodedPath}` : '';
+    return target && !/[)\s]/.test(target) ? target : '';
+  } catch (_) { return ''; }
+}
+function encodeGithubPath(value = '') {
+  return String(value).split('/').map((part) => encodeURIComponent(part).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)).join('/');
+}
+function exactCommit(value = '') { const commit = token(value); return /^[0-9a-f]{40}$/i.test(commit) ? commit : ''; }
+function relativeArtifactPath(fromPath = '', toPath = '') {
+  const from = normalizePathParts(fromPath); const to = normalizePathParts(toPath);
+  if (!from.length || !to.length) return '';
+  from.pop();
+  let shared = 0; while (shared < from.length && shared < to.length && from[shared] === to[shared]) shared += 1;
+  const parts = [...Array(from.length - shared).fill('..'), ...to.slice(shared)];
+  return parts.join('/') || to[to.length - 1] || '';
+}
+function normalizePathParts(value = '') {
+  const out = []; for (const part of String(value || '').replace(/\\/g, '/').split('/')) { if (!part || part === '.') continue; if (part === '..') out.pop(); else out.push(part); } return out;
+}
+function markdownLabel(value) { return String(value || '').replace(/[\[\]\n\r]/g, ' ').trim() || 'Topic'; }
+function token(value = '') { return String(value || '').trim(); }

package/src/transitions/transition.presentation.js

@@ -0,0 +1,43 @@
+import { transitionDefinitionsForRecord } from './transition.definitions.js';
+import { legacyIconForIntent, legacyIntentDisplayLabel } from './transition.legacyShorthand.js';
+
+export const TRANSITION_ACTION_PRESENTATION_CONTRACT_ID = 'tiinex.transition.action.presentation.v1';
+export const RECORD_TRANSITION_ACTION_PREFIX = 'record.transition';
+
+export function transitionActionsForRecord(record = {}, options = {}) {
+  const maxPrimary = Number.isFinite(Number(options.maxPrimary)) ? Math.max(0, Number(options.maxPrimary)) : 1;
+  const definitions = transitionDefinitionsForRecord(record, options);
+  const primary = definitions.filter((definition) => definition.presentation?.placement === 'primary');
+  const grouped = definitions.filter((definition) => definition.presentation?.placement !== 'primary');
+  const picked = primary.slice(0, maxPrimary).concat(maxPrimary > primary.length ? grouped.slice(0, maxPrimary - primary.length) : []);
+  return picked.map((definition) => transitionActionForDefinition(definition));
+}
+
+export function transitionActionForDefinition(definition = {}) {
+  const presentation = definition.presentation || {};
+  const intentLabel = legacyIntentDisplayLabel(definition.intent);
+  const label = presentation.tooltip || `${intentLabel} · ${definition.label || definition.shortLabel || definition.id}`;
+  return Object.freeze({
+    id: transitionActionId(definition.id),
+    label,
+    shortLabel: definition.shortLabel || definition.label || definition.id,
+    icon: presentation.icon || legacyIconForIntent(definition.intent),
+    enabled: definition.status === 'active',
+    contract: TRANSITION_ACTION_PRESENTATION_CONTRACT_ID,
+    capabilityStatus: 'implemented',
+    produces: definition.resultSchema || definition.resultKind || '',
+    intent: definition.intent || '',
+    group: presentation.group || intentLabel,
+    definitionId: definition.id || '',
+    presentation,
+    transitionDefinition: definition
+  });
+}
+
+export function isTransitionAction(action = {}) {
+  return Boolean(action?.transitionDefinition || String(action?.id || '').startsWith(`${RECORD_TRANSITION_ACTION_PREFIX}:`));
+}
+
+export function transitionActionId(definitionId = '') {
+  return `${RECORD_TRANSITION_ACTION_PREFIX}:${String(definitionId || '').trim()}`;
+}