@tiinex/app 0.1.1

package/src/transitions/transition.productPreparation.js

@@ -0,0 +1,377 @@
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { buildLoadedArtifactParticipantIndex, resolveCurrentArtifactParticipant } from '../artifacts/artifact.participantIndex.js';
+import { compilePortableSchemaContractChain } from '@tiinex/core/tooling/portable/schema/contract.compile.js';
+import { CANONICAL_TRANSITION_SCHEMA_CACHE_MANIFEST, qualifyCanonicalTransitionSchemaCacheSubset } from './canonicalTransition.schemaCache.js';
+import { buildTransitionDefinitionRegistry } from './transition.definitionRegistry.js';
+import { buildCanonicalTransitionAvailabilityPlan } from './transition.availabilityPlanner.js';
+import { buildCanonicalTransitionResultPlan } from './transition.resultSemantics.js';
+import { localArtifactMaterializerForSchema } from './transition.localArtifactMaterializers.js';
+import { localCreateCapability } from './transition.localCreateCapability.js';
+import { referenceCreateCapability } from './transition.referenceCreateCapability.js';
+import { qualifyPortableExplicitGenerationBinding } from '@tiinex/core/tooling/portable/package/generation.binding.js';
+import { recoverCanonicalParentReference, unavailableCanonicalParentReference } from './transition.parentReference.js';
+import { qualifyExactAuthorityRepresentation } from './transition.authorityRepresentation.js';
+export { recoverCanonicalParentReference, finalizeCanonicalParentReference } from './transition.parentReference.js';
+
+export const CANONICAL_TRANSITION_PRODUCT_PREPARATION_SCHEMA_ID = 'tiinex.site.canonical-transition-product-preparation.v1';
+export const CANONICAL_LOCAL_CREATE_CAPABILITY_SCHEMA_ID = 'tiinex.site.canonical-transition-local-create-capability.v1';
+export const CANONICAL_TRANSITION_PRODUCT_CONTEXT_SCHEMA_ID = 'tiinex.site.canonical-transition-product-context.v1';
+const TASK_SCHEMA_ID = 'tiinex.task.v1';
+const ROOT_SCHEMA_ID = 'tiinex.root.v1';
+const TRANSITION_SCHEMA_ID = 'tiinex.transition.definition.v1';
+const SCHEMA_CONTRACT_SCHEMA_ID = 'tiinex.schema.contract.v1';
+const SCHEMA_GENERATION_SCHEMA_ID = 'tiinex.schema.generation.v1';
+const freeze = Object.freeze;
+
+export function prepareCanonicalTransitionProductContext(input = {}) {
+  const workspaceRecords = Array.isArray(input.workspaceRecords) ? input.workspaceRecords : [];
+  const referenceRecords = Array.isArray(input.referenceRecords) ? input.referenceRecords : workspaceRecords;
+  const schemaCache = Array.isArray(input.schemaCache) ? input.schemaCache : [];
+  const bundledDefinitions = Array.isArray(input.bundledDefinitions) ? input.bundledDefinitions : [];
+  const cacheQualification = qualifyProductSchemaCache(schemaCache);
+  const participantIndex = buildLoadedArtifactParticipantIndex({ records: workspaceRecords });
+  const referenceParticipantIndex = referenceRecords === workspaceRecords ? participantIndex : buildLoadedArtifactParticipantIndex({ records: referenceRecords });
+  if (!cacheQualification.sourceQualified) return productContext({ workspaceRecords, referenceRecords, schemaCache, bundledDefinitions, participantIndex, referenceParticipantIndex, cacheQualification, state: 'schema-cache-unqualified' });
+
+  const cache = Object.fromEntries(cacheQualification.entries.map((item) => [item.schemaId, item]));
+  const creationAuthorities = buildCreationAuthorities(cacheQualification.entries);
+  const definitionMaterials = [cache[ROOT_SCHEMA_ID]?.markdown || '', cache[TRANSITION_SCHEMA_ID]?.markdown || ''];
+  const resolvers = buildProductSchemaResolvers(participantIndex, cacheQualification.entries, creationAuthorities);
+  const records = workspaceRecords.concat(bundledDefinitionRecords(bundledDefinitions));
+  const registry = buildTransitionDefinitionRegistry({ records, schemaMaterials: definitionMaterials, resolvers });
+  const explicitGenerationAuthorities = buildExplicitGenerationAuthorities({ cache, registry, bundledDefinitions });
+  return productContext({ workspaceRecords, referenceRecords, schemaCache, bundledDefinitions, participantIndex, referenceParticipantIndex, cacheQualification, cache, creationAuthorities, explicitGenerationAuthorities, registry, state: 'prepared' });
+}
+
+export function prepareCanonicalTransitionProductActions(input = {}) {
+  const workspaceRecords = Array.isArray(input.workspaceRecords) ? input.workspaceRecords : [];
+  const referenceRecords = Array.isArray(input.referenceRecords) ? input.referenceRecords : workspaceRecords;
+  const schemaCache = Array.isArray(input.schemaCache) ? input.schemaCache : [];
+  const bundledDefinitions = Array.isArray(input.bundledDefinitions) ? input.bundledDefinitions : [];
+  const context = productContextMatches(input.productContext, workspaceRecords, referenceRecords, schemaCache, bundledDefinitions)
+    ? input.productContext
+    : prepareCanonicalTransitionProductContext({ workspaceRecords, referenceRecords, schemaCache, bundledDefinitions });
+  const participantIndex = context.participantIndex;
+  const currentParticipant = resolveCurrentArtifactParticipant(input.currentRecord, participantIndex);
+  if (!context.cacheQualification?.sourceQualified) return preparation([], participantIndex, currentParticipant, context.cacheQualification, 'schema-cache-unqualified');
+
+  const definitions = context.registry?.definitions || [];
+  const availabilityPlan = buildCanonicalTransitionAvailabilityPlan({ definitions, participantIndex, currentArtifact: currentParticipant || input.currentRecord });
+  const referenceParticipantIndex = context.referenceParticipantIndex || participantIndex;
+  const referenceCurrentParticipant = referenceParticipantIndex === participantIndex
+    ? currentParticipant
+    : resolveCurrentArtifactParticipant(input.currentRecord, referenceParticipantIndex);
+  const referenceAvailabilityPlan = referenceParticipantIndex === participantIndex
+    ? availabilityPlan
+    : buildCanonicalTransitionAvailabilityPlan({ definitions, participantIndex: referenceParticipantIndex, currentArtifact: referenceCurrentParticipant || input.currentRecord });
+  const referenceAvailabilityByDefinition = new Map(referenceAvailabilityPlan.transitions.map((item) => [availabilityDefinitionKey(item), item]));
+  const actions = availabilityPlan.transitions.map((localAvailability) => {
+    const definition = definitionForAvailability(definitions, localAvailability);
+    const result = definition ? buildCanonicalTransitionResultPlan({ definition }) : null;
+    const reference = Boolean((result?.relationEffects || []).length);
+    const availability = reference ? (referenceAvailabilityByDefinition.get(availabilityDefinitionKey(localAvailability)) || localAvailability) : localAvailability;
+    return buildProductAction({
+      definition,
+      availability,
+      participantIndex: reference ? referenceParticipantIndex : participantIndex,
+      currentParticipant: reference ? referenceCurrentParticipant : currentParticipant,
+      currentRecord: input.currentRecord,
+      workspaceId: input.workspaceId,
+      cache: context.cache,
+      creationAuthorities: context.creationAuthorities,
+      explicitGenerationAuthorities: context.explicitGenerationAuthorities,
+      productScope: 'record'
+    });
+  }).filter((action) => action?.capability?.scope === 'record');
+  return preparation(actions, participantIndex, currentParticipant, context.cacheQualification, 'prepared', context.registry);
+}
+
+
+export function prepareCanonicalTransitionWorkspaceActions(input = {}) {
+  const schemaCache = Array.isArray(input.schemaCache) ? input.schemaCache : [];
+  const bundledDefinitions = Array.isArray(input.bundledDefinitions) ? input.bundledDefinitions : [];
+  // Workspace-level standalone Create is intentionally derived from exact bundled
+  // zero-input definitions. It does not rebuild a participant index from every card.
+  const context = prepareCanonicalTransitionProductContext({ workspaceRecords: [], schemaCache, bundledDefinitions });
+  const participantIndex = context.participantIndex;
+  if (!context.cacheQualification?.sourceQualified) return preparation([], participantIndex, null, context.cacheQualification, 'schema-cache-unqualified', context.registry);
+
+  const availabilityPlan = buildCanonicalTransitionAvailabilityPlan({
+    definitions: context.registry?.definitions || [],
+    participantIndex,
+    currentArtifact: null
+  });
+  const actions = availabilityPlan.transitions.map((availability) => {
+    const definition = definitionForAvailability(context.registry?.definitions || [], availability);
+    return buildProductAction({
+      definition,
+      availability,
+      participantIndex,
+      currentParticipant: null,
+      currentRecord: null,
+      workspaceId: input.workspaceId,
+      cache: context.cache,
+      creationAuthorities: context.creationAuthorities,
+      explicitGenerationAuthorities: context.explicitGenerationAuthorities,
+      productScope: 'workspace'
+    });
+  }).filter((action) => action?.capability?.scope === 'workspace');
+  return preparation(actions, participantIndex, null, context.cacheQualification, 'prepared', context.registry);
+}
+
+function productContext(input = {}) {
+  return freeze({
+    schema: CANONICAL_TRANSITION_PRODUCT_CONTEXT_SCHEMA_ID,
+    state: input.state || 'prepared',
+    workspaceRecords: input.workspaceRecords || [],
+    referenceRecords: input.referenceRecords || input.workspaceRecords || [],
+    schemaCache: input.schemaCache || [],
+    bundledDefinitions: input.bundledDefinitions || [],
+    participantIndex: input.participantIndex || buildLoadedArtifactParticipantIndex({ records: [] }),
+    referenceParticipantIndex: input.referenceParticipantIndex || input.participantIndex || buildLoadedArtifactParticipantIndex({ records: [] }),
+    cacheQualification: input.cacheQualification || null,
+    cache: freeze({ ...(input.cache || {}) }),
+    creationAuthorities: freeze({ ...(input.creationAuthorities || {}) }),
+    explicitGenerationAuthorities: freeze({ ...(input.explicitGenerationAuthorities || {}) }),
+    registry: input.registry || null,
+    readOnly: true,
+    mutation: false,
+    networkFetch: false
+  });
+}
+
+function productContextMatches(context, workspaceRecords, referenceRecords, schemaCache, bundledDefinitions) {
+  return context?.schema === CANONICAL_TRANSITION_PRODUCT_CONTEXT_SCHEMA_ID
+    && context.workspaceRecords === workspaceRecords
+    && context.referenceRecords === referenceRecords
+    && context.schemaCache === schemaCache
+    && context.bundledDefinitions === bundledDefinitions;
+}
+
+function qualifyProductSchemaCache(entries = []) {
+  const foundation = qualifyCanonicalTransitionSchemaCacheSubset(entries, [ROOT_SCHEMA_ID, TRANSITION_SCHEMA_ID]);
+  if (!foundation.sourceQualified) return foundation;
+  const qualifiedById = new Map(foundation.entries.map((item) => [item.schemaId, item]));
+  const findings = [...foundation.findings];
+  for (const expected of CANONICAL_TRANSITION_SCHEMA_CACHE_MANIFEST) {
+    if (expected.schemaId === ROOT_SCHEMA_ID || expected.schemaId === TRANSITION_SCHEMA_ID) continue;
+    const matches = (Array.isArray(entries) ? entries : []).filter((item) => String(item?.schemaId || '') === expected.schemaId);
+    if (!matches.length) continue;
+    const result = qualifyCanonicalTransitionSchemaCacheSubset(entries, [expected.schemaId]);
+    if (result.sourceQualified) qualifiedById.set(expected.schemaId, result.entries[0]);
+    else findings.push(...result.findings);
+  }
+  return freeze({
+    status: 'qualified',
+    sourceQualified: true,
+    entries: freeze([...qualifiedById.values()]),
+    findings: freeze(findings),
+    foundationQualified: true
+  });
+}
+
+export function creationAuthorityForSchemaFromCache(cacheEntries = [], schemaId = '') {
+  const targetSchemaId = token(schemaId);
+  const cacheQualification = qualifyCanonicalTransitionSchemaCacheSubset(cacheEntries, [ROOT_SCHEMA_ID, targetSchemaId]);
+  if (!targetSchemaId || !cacheQualification.sourceQualified) return unresolvedCreationAuthority(targetSchemaId);
+  const bySchema = Object.fromEntries(cacheQualification.entries.map((item) => [item.schemaId, item]));
+  if (!bySchema[ROOT_SCHEMA_ID]?.markdown || !bySchema[targetSchemaId]?.markdown) return unresolvedCreationAuthority(targetSchemaId);
+  try {
+    const compiled = compilePortableSchemaContractChain([bySchema[ROOT_SCHEMA_ID].markdown, bySchema[targetSchemaId].markdown]);
+    const creation = compiled.creation || {};
+    const usable = compiled.schemaId === targetSchemaId
+      && compiled.lineageQualification?.state === 'valid'
+      && compiled.lineageQualification?.complete === true
+      && (creation.requiredInputs || []).length > 0;
+    return freeze({
+      state: usable ? 'qualified' : 'unresolved',
+      schemaId: targetSchemaId,
+      requiredInputs: freeze([...(creation.requiredInputs || [])]),
+      optionalInputs: freeze([...(creation.optionalInputs || [])]),
+      requiredSections: freeze([...(creation.requiredSections || [])]),
+      toolingConfigurationFields: freeze([...(creation.toolingConfigurationFields || [])]),
+      compiled: usable ? compiled : null
+    });
+  } catch (_) { return unresolvedCreationAuthority(targetSchemaId); }
+}
+
+export function taskCreationAuthorityFromCache(cacheEntries = []) {
+  return creationAuthorityForSchemaFromCache(cacheEntries, TASK_SCHEMA_ID);
+}
+
+function unresolvedCreationAuthority(schemaId = '') {
+  return freeze({ state: 'unresolved', schemaId: token(schemaId), requiredInputs: freeze([]), optionalInputs: freeze([]), requiredSections: freeze([]), toolingConfigurationFields: freeze([]), compiled: null });
+}
+
+function buildProductAction({ definition, availability, participantIndex, currentParticipant, currentRecord, workspaceId, cache, creationAuthorities, explicitGenerationAuthorities, productScope = 'record' }) {
+  if (!definition) return null;
+  const result = buildCanonicalTransitionResultPlan({ definition });
+  const output = result.outputRoles?.[0];
+  const outputSchemaId = token(output?.schemaConstraint);
+  const creation = creationAuthorities?.[outputSchemaId] || unresolvedCreationAuthority(outputSchemaId);
+  const parent = productScope === 'workspace' ? null : (currentParticipant ? recoverCanonicalParentReference(currentRecord || {}, currentParticipant) : unavailableCanonicalParentReference('current-artifact-not-resolved'));
+  const materializer = localArtifactMaterializerForSchema(outputSchemaId);
+  const invocationRepresentationBindings = freeze({ parentTarget: canonicalSourceTargetForParent(parent) });
+  const fixedInputs = materializer?.authoringInputsFromInvocationBindings
+    ? freeze({ ...(materializer.authoringInputsFromInvocationBindings(invocationRepresentationBindings) || {}) })
+    : freeze({});
+  const identity = definition.transitionIdentity || {};
+  const executionKey = definitionExecutionKey(definition);
+  const explicitGeneration = explicitGenerationAuthorities?.[`${executionKey}\u0000${output?.name || ''}`] || null;
+  const referenceSupport = productScope === 'record' && (result.relationEffects || []).length
+    ? referenceCreateCapability({ result, availability, currentParticipant, workspaceId, generationQualification: explicitGeneration, materializer })
+    : null;
+  const support = referenceSupport || localCreateCapability({ result, availability, creation, currentParticipant, workspaceId, parent, materializer, productScope });
+  return freeze({
+    schema: CANONICAL_LOCAL_CREATE_CAPABILITY_SCHEMA_ID,
+    id: `canonical-transition:${executionKey}`,
+    canonicalIdentifier: String(identity['Canonical Identifier'] || ''),
+    label: String(identity['Human Label'] || identity.Name || 'Transition'),
+    icon: canonicalTransitionProductIcon({ productScope, result, creation, referenceSupport, support }),
+    kind: 'canonical-transition-product',
+    productScope,
+    description: String(definition.purposeAndScope?.Purpose || definition.purposeAndScope?.purpose || ''),
+    continuityMode: support.continuityMode || 'parent',
+    definitionKey: executionKey,
+    identityConflict: null,
+    definition,
+    availability,
+    resultSemantics: result,
+    currentParticipant,
+    parentRecovery: parent,
+    authoring: freeze({
+      schemaId: outputSchemaId,
+      schemaLabel: materializer?.label || outputSchemaId || 'Artifact',
+      requiredInputs: creation.requiredInputs,
+      optionalInputs: creation.optionalInputs,
+      requiredSections: creation.requiredSections,
+      toolingConfigurationFields: creation.toolingConfigurationFields,
+      fixedInputs
+    }),
+    explicitGenerationQualification: explicitGeneration,
+    referenceCapability: referenceSupport,
+    productCapable: support.state === 'qualified',
+    capability: support,
+    enabled: support.state === 'qualified'
+  });
+}
+
+
+function canonicalTransitionProductIcon({ productScope = 'record', result = {}, creation = {}, referenceSupport = null, support = {} } = {}) {
+  if (referenceSupport || (result.relationEffects || []).length) return 'reference';
+  if (productScope === 'workspace' || support.continuityMode === 'root') return 'create';
+  if (support.continuityMode === 'parent' || (result.parentEffects || []).length) return 'continue';
+  return 'create';
+}
+
+
+function buildExplicitGenerationAuthorities({ cache = {}, registry = null, bundledDefinitions = [] } = {}) {
+  const out = {};
+  const root = cache[ROOT_SCHEMA_ID]?.markdown || '';
+  const transitionSchema = cache[TRANSITION_SCHEMA_ID]?.markdown || '';
+  const schemaContract = cache[SCHEMA_CONTRACT_SCHEMA_ID]?.markdown || '';
+  const generationSchema = cache[SCHEMA_GENERATION_SCHEMA_ID]?.markdown || '';
+  if (!root || !transitionSchema || !schemaContract || !generationSchema) return freeze(out);
+  let transitionContract, generationContract;
+  try {
+    transitionContract = compilePortableSchemaContractChain([root, transitionSchema]);
+    generationContract = compilePortableSchemaContractChain([root, schemaContract, generationSchema]);
+  } catch (_) { return freeze(out); }
+  if (transitionContract.lineageQualification?.state !== 'valid' || transitionContract.lineageQualification?.complete !== true) return freeze(out);
+  if (generationContract.lineageQualification?.state !== 'valid' || generationContract.lineageQualification?.complete !== true) return freeze(out);
+
+  for (const supplied of Array.isArray(bundledDefinitions) ? bundledDefinitions : []) {
+    const generationMaterials = Array.isArray(supplied?.generationMaterials) ? supplied.generationMaterials : [];
+    if (!generationMaterials.length) continue;
+    const definition = exactOne((registry?.definitions || []).filter((candidate) => token(candidate?.artifact?.path) === token(supplied.path)));
+    if (!definition) continue;
+    const result = buildCanonicalTransitionResultPlan({ definition });
+    for (const output of result.outputRoles || []) {
+      const declared = token(output.generationBinding);
+      if (!declared || declared === 'target-schema') continue;
+      const transitionMaterial = freeze({
+        id: supplied.id || `bundled-transition:${definitionExecutionKey(definition)}`,
+        path: supplied.path || '',
+        markdown: supplied.markdown || '',
+        source: freeze({ ...(supplied.source || {}) })
+      });
+      const qualification = qualifyPortableExplicitGenerationBinding({
+        transitionMaterial,
+        outputRoleName: output.name,
+        expectedTargetSchema: token(output.schemaConstraint),
+        materials: [transitionMaterial, ...generationMaterials],
+        transitionContract,
+        generationContract
+      });
+      const selectedPath = token(qualification.authority?.selectedRepresentation?.path);
+      const generationMaterial = exactOne(generationMaterials.filter((item) => token(item?.path) === selectedPath));
+      const exactAuthorityRepresentations = freeze({
+        transition: qualifyExactAuthorityRepresentation({
+          reference: transitionMaterial.path ? `site-local:${transitionMaterial.path}` : '',
+          path: transitionMaterial.path,
+          markdown: transitionMaterial.markdown
+        }),
+        generation: qualifyExactAuthorityRepresentation({
+          reference: token(qualification.resolution?.target),
+          path: generationMaterial?.path || '',
+          markdown: generationMaterial?.markdown || ''
+        })
+      });
+      out[`${definitionExecutionKey(definition)}\u0000${output.name}`] = freeze({ ...qualification, exactAuthorityRepresentations });
+    }
+  }
+  return freeze(out);
+}
+
+
+function buildCreationAuthorities(cacheEntries = []) {
+  const out = {};
+  for (const entry of cacheEntries || []) {
+    const schemaId = token(entry?.schemaId);
+    if (!schemaId || schemaId === ROOT_SCHEMA_ID || schemaId === TRANSITION_SCHEMA_ID) continue;
+    out[schemaId] = creationAuthorityForSchemaFromCache(cacheEntries, schemaId);
+  }
+  return freeze(out);
+}
+
+function buildProductSchemaResolvers(participantIndex, cacheEntries, creationAuthorities = {}) {
+  const schemaAuthorities = {};
+  for (const participant of participantIndex.participants || []) if (participant.cleanCandidate && participant.candidateSchemaId) schemaAuthorities[participant.candidateSchemaId] = freeze({ targetKind: 'artifact' });
+  for (const entry of cacheEntries || []) {
+    const schemaId = token(entry?.schemaId);
+    if (!schemaId || schemaId === ROOT_SCHEMA_ID || schemaId === TRANSITION_SCHEMA_ID) continue;
+    const creation = creationAuthorities[schemaId] || unresolvedCreationAuthority(schemaId);
+    schemaAuthorities[schemaId] = freeze({ ...(schemaAuthorities[schemaId] || {}), targetKind: 'artifact', generation: creation.state === 'qualified' });
+  }
+  return freeze({ schemaAuthorities: freeze(schemaAuthorities) });
+}
+
+function bundledDefinitionRecords(definitions = []) {
+  return (Array.isArray(definitions) ? definitions : []).map((item) => Object.assign(createRecordFromMarkdown(String(item.markdown || ''), { path: item.path || '', name: item.title || '', sourceMode: item.sourceMode || 'bundled-canonical-transition-definition' }), item));
+}
+function preparation(actions, participantIndex, currentParticipant, cacheQualification, state, registry = null, identityConflicts = []) {
+  return freeze({ schema: CANONICAL_TRANSITION_PRODUCT_PREPARATION_SCHEMA_ID, state, actions: freeze(actions), participantIndex, currentParticipant, cacheQualification, registry, identityConflicts: freeze(identityConflicts), readOnly: true, mutation: false, networkFetch: false });
+}
+function availabilityDefinitionKey(availability = {}) {
+  return token(availability.definition?.artifactRegistryIdentity || availability.definition?.artifactId || availability.definition?.canonicalIdentifier);
+}
+function definitionForAvailability(definitions = [], availability = {}) {
+  const registryIdentity = token(availability.definition?.artifactRegistryIdentity);
+  if (registryIdentity) return exactOne(definitions.filter((candidate) => token(candidate.artifact?.registryIdentity) === registryIdentity));
+  const artifactId = token(availability.definition?.artifactId);
+  return artifactId ? exactOne(definitions.filter((candidate) => token(candidate.artifact?.id) === artifactId)) : null;
+}
+function definitionExecutionKey(definition = {}) {
+  return JSON.stringify([token(definition.transitionIdentity?.['Canonical Identifier']), token(definition.artifact?.registryIdentity || definition.artifact?.id)]);
+}
+function exactOne(values = []) { return values.length === 1 ? values[0] : null; }
+function markdownLabel(value) { return String(value || '').replace(/[\[\]\n\r]/g, ' ').trim() || 'Topic'; }
+function canonicalSourceTargetForParent(parent = {}) {
+  const traceTarget = token(parent?.traceTarget);
+  const originTarget = token(parent?.originTarget);
+  const kind = token(parent?.representationKind);
+  if ((kind === 'github-issue-embedded' || kind === 'github-comment-embedded') && traceTarget && originTarget) return `${traceTarget} @ ${originTarget}`;
+  return traceTarget || originTarget;
+}
+
+function token(value = '') { return String(value || '').trim(); }

package/src/transitions/transition.productPresentation.browser.js

@@ -0,0 +1,28 @@
+import { transitionProductActionsForRecord as transitionProductActionsForRecordPure, transitionProductActionsForWorkspace as transitionProductActionsForWorkspacePure, transitionProductContextForWorkspace as transitionProductContextForWorkspacePure, isCanonicalTransitionProductAction, CANONICAL_TRANSITION_PRODUCT_ACTION_KIND, LEGACY_CANONICAL_PRESENTATION_COMPATIBILITY } from './transition.productPresentation.js';
+import { BUNDLED_CANONICAL_TRANSITION_DEFINITIONS, BUNDLED_CANONICAL_TRANSITION_SCHEMA_CACHE } from './canonicalTransition.productDefaults.js';
+
+export { isCanonicalTransitionProductAction, CANONICAL_TRANSITION_PRODUCT_ACTION_KIND, LEGACY_CANONICAL_PRESENTATION_COMPATIBILITY };
+export function transitionProductActionsForRecord(record = {}, options = {}) {
+  return transitionProductActionsForRecordPure(record, {
+    ...options,
+    schemaCache: options.schemaCache || BUNDLED_CANONICAL_TRANSITION_SCHEMA_CACHE,
+    bundledDefinitions: options.bundledDefinitions || BUNDLED_CANONICAL_TRANSITION_DEFINITIONS
+  });
+}
+
+
+export function transitionProductActionsForWorkspace(options = {}) {
+  return transitionProductActionsForWorkspacePure({
+    ...options,
+    schemaCache: options.schemaCache || BUNDLED_CANONICAL_TRANSITION_SCHEMA_CACHE,
+    bundledDefinitions: options.bundledDefinitions || BUNDLED_CANONICAL_TRANSITION_DEFINITIONS
+  });
+}
+
+export function transitionProductContextForWorkspace(options = {}) {
+  return transitionProductContextForWorkspacePure({
+    ...options,
+    schemaCache: options.schemaCache || BUNDLED_CANONICAL_TRANSITION_SCHEMA_CACHE,
+    bundledDefinitions: options.bundledDefinitions || BUNDLED_CANONICAL_TRANSITION_DEFINITIONS
+  });
+}

package/src/transitions/transition.productPresentation.js

@@ -0,0 +1,55 @@
+import { transitionActionsForRecord } from './transition.presentation.js';
+import { prepareCanonicalTransitionProductActions, prepareCanonicalTransitionProductContext, prepareCanonicalTransitionWorkspaceActions } from './transition.productPreparation.js';
+import { CANONICAL_TOPIC_TO_TASK_BUNDLED_SOURCE_ID } from './canonicalTransition.semanticPackage.js';
+
+export const CANONICAL_TRANSITION_PRODUCT_ACTION_KIND = 'canonical-transition-product';
+export const LEGACY_CANONICAL_PRESENTATION_COMPATIBILITY = Object.freeze({
+  'tiinex.site.topic-to-task.v1': 'topic.continue.task'
+});
+
+export function transitionProductActionsForRecord(record = {}, options = {}) {
+  const schemaCache = Array.isArray(options.schemaCache) ? options.schemaCache : [];
+  const bundledDefinitions = Array.isArray(options.bundledDefinitions) ? options.bundledDefinitions : [];
+  const workspaceRecords = options.workspaceRecords || [];
+  const referenceRecords = options.referenceRecords || workspaceRecords;
+  const preparation = prepareCanonicalTransitionProductActions({ currentRecord: record, workspaceRecords, referenceRecords, workspaceId: options.workspaceId || '', schemaCache, bundledDefinitions, productContext: options.productContext || null });
+  const preparedActions = preparation.actions || [];
+  const canonical = preparedActions.filter((action) => action.productCapable).map((action) => Object.freeze({ ...action, kind: CANONICAL_TRANSITION_PRODUCT_ACTION_KIND, transitionProductPreparationState: preparation.state }));
+  const suppressedLegacyDefinitionIds = new Set(preparedActions.map(exactBundledCompatibilityDefinitionId).filter(Boolean));
+  const legacy = transitionActionsForRecord(record, options).filter((action) => !suppressedLegacyDefinitionIds.has(action.definitionId));
+  return Object.freeze([...canonical, ...legacy]);
+}
+
+
+export function transitionProductActionsForWorkspace(options = {}) {
+  const schemaCache = Array.isArray(options.schemaCache) ? options.schemaCache : [];
+  const bundledDefinitions = Array.isArray(options.bundledDefinitions) ? options.bundledDefinitions : [];
+  const preparation = prepareCanonicalTransitionWorkspaceActions({
+    workspaceId: options.workspaceId || '',
+    schemaCache,
+    bundledDefinitions
+  });
+  return Object.freeze((preparation.actions || []).map((action) => Object.freeze({
+    ...action,
+    kind: CANONICAL_TRANSITION_PRODUCT_ACTION_KIND,
+    transitionProductPreparationState: preparation.state
+  })));
+}
+
+export function transitionProductContextForWorkspace(options = {}) {
+  return prepareCanonicalTransitionProductContext({
+    workspaceRecords: Array.isArray(options.workspaceRecords) ? options.workspaceRecords : [],
+    referenceRecords: Array.isArray(options.referenceRecords) ? options.referenceRecords : (Array.isArray(options.workspaceRecords) ? options.workspaceRecords : []),
+    schemaCache: Array.isArray(options.schemaCache) ? options.schemaCache : [],
+    bundledDefinitions: Array.isArray(options.bundledDefinitions) ? options.bundledDefinitions : []
+  });
+}
+export function isCanonicalTransitionProductAction(action = {}) { return action?.kind === CANONICAL_TRANSITION_PRODUCT_ACTION_KIND; }
+
+function exactBundledCompatibilityDefinitionId(action = {}) {
+  const source = action.definition?.source || {};
+  return action.canonicalIdentifier === 'tiinex.site.topic-to-task.v1'
+    && source.sourceMode === 'bundled-canonical-transition-definition'
+    && source.sourceId === CANONICAL_TOPIC_TO_TASK_BUNDLED_SOURCE_ID
+    ? LEGACY_CANONICAL_PRESENTATION_COMPATIBILITY[action.canonicalIdentifier] : '';
+}

package/src/transitions/transition.referenceCreateCapability.js

@@ -0,0 +1,119 @@
+export const CANONICAL_REFERENCE_CREATE_CAPABILITY_SCHEMA_ID = 'tiinex.site.canonical-reference-create-capability.v1';
+const freeze = Object.freeze;
+
+export function referenceCreateCapability(input = {}) {
+  const reasons = [];
+  const { result = {}, availability = {}, currentParticipant = null, workspaceId = '', generationQualification = null, materializer = null } = input;
+  const outputs = result.outputRoles || [];
+  const output = outputs[0];
+  const inputs = availability.inputRoles || [];
+  const currentRoleIds = availability.context?.candidateRoleIds || [];
+  const lifecycle = result.lifecycleEffects || [];
+  const parents = result.parentEffects || [];
+  const relations = result.relationEffects || [];
+  const placements = result.outputPlacements || [];
+  const destinations = result.destinationBindings || [];
+  const relation = relations[0];
+  const currentRoleName = currentRoleIds.length === 1 ? currentRoleIds[0] : '';
+  const currentRole = inputs.find((role) => role.name === currentRoleName);
+  const targetRoleName = relation?.objectBinding?.resolvedName || '';
+  const targetRole = inputs.find((role) => role.name === targetRoleName);
+  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 (inputs.length !== 2) reasons.push('reference-requires-two-input-roles');
+  if (outputs.length !== 1 || outputSchemaId !== 'tiinex.relation.v1') reasons.push('reference-relation-output-unqualified');
+  if (!currentRoleName || relation?.subjectBinding?.resolvedName !== currentRoleName) reasons.push('reference-subject-not-current-artifact-role');
+  if (!supportedExistingArtifactRole(currentRole) || currentParticipant?.candidateSchemaId !== currentRole?.schemaConstraint) reasons.push('reference-subject-schema-unqualified');
+  if (!targetRoleName || targetRoleName === currentRoleName || !supportedExistingArtifactRole(targetRole)) reasons.push('reference-target-role-unqualified');
+  if (!Array.isArray(targetRole?.cleanCandidateIds) || targetRole.cleanCandidateIds.length < 1) reasons.push('reference-target-candidate-unavailable');
+  if (!supportedOutput(output)) reasons.push('reference-output-generation-unqualified');
+  if (lifecycle.length !== 1 || !supportedLifecycle(lifecycle[0], output)) reasons.push('reference-lifecycle-unqualified');
+  if (parents.length !== 0) reasons.push('reference-parent-effect-not-allowed');
+  if (relations.length !== 1 || !supportedRelationEffect(relation, currentRoleName, targetRoleName)) reasons.push('reference-relation-effect-unqualified');
+  if (!supportedLocalPlacement(placements, destinations, output)) reasons.push('reference-placement-unqualified');
+  if (generationQualification?.qualification !== 'qualified'
+    || generationQualification.outputRoleName !== output?.name
+    || generationQualification.expectedTargetSchema !== outputSchemaId
+    || generationQualification.authority?.generationTargetSchema !== outputSchemaId
+    || generationQualification.declaredBinding !== output?.generationBinding) reasons.push('reference-generation-authority-unqualified');
+  const exactRepresentations = generationQualification?.exactAuthorityRepresentations || {};
+  if (exactRepresentations.transition?.state !== 'qualified'
+    || exactRepresentations.generation?.state !== 'qualified'
+    || exactRepresentations.generation?.reference !== generationQualification?.resolution?.target) reasons.push('reference-exact-authority-representation-unqualified');
+  if (!materializer || materializer.schemaId !== outputSchemaId) reasons.push('reference-local-materializer-unavailable');
+  if (!token(workspaceId)) reasons.push('workspace-destination-unavailable');
+
+  const uniqueReasons = unique(reasons);
+  return freeze({
+    schema: CANONICAL_REFERENCE_CREATE_CAPABILITY_SCHEMA_ID,
+    state: uniqueReasons.length ? 'unavailable' : 'qualified',
+    reasons: freeze(uniqueReasons),
+    scope: 'record',
+    continuityMode: 'root',
+    subjectRole: currentRoleName,
+    targetRole: targetRoleName,
+    targetSchemaId: token(targetRole?.schemaConstraint),
+    targetCandidateParticipantIds: freeze([...(targetRole?.cleanCandidateIds || [])].filter((id) => id !== currentParticipant?.identity?.id)),
+    outputRole: output?.name || '',
+    outputSchemaId,
+    relationEffect: relation || null,
+    generationQualification,
+    remoteWrite: false,
+    sourceMutation: false,
+    targetMutation: false,
+    relationMaterialization: uniqueReasons.length === 0,
+    concretePath: null,
+    executablePattern: uniqueReasons.length === 0
+  });
+}
+
+function supportedExistingArtifactRole(role = {}) {
+  return role?.targetKind === 'artifact' && role?.effectiveParticipantKind === 'artifact'
+    && Boolean(token(role?.schemaConstraint)) && role?.acquisitionPolicy === 'existing-only'
+    && exactCount(role?.cardinality?.minimum, 1) && exactCount(role?.cardinality?.maximum, 1);
+}
+function supportedOutput(role = {}) {
+  return role?.targetKind === 'artifact' && role?.effectiveParticipantKind === 'artifact'
+    && token(role?.schemaConstraint) === 'tiinex.relation.v1'
+    && exactCount(role?.minimumCount, 1) && exactCount(role?.maximumCount, 1)
+    && Boolean(token(role?.generationBinding)) && role?.generationBinding !== 'target-schema';
+}
+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 supportedRelationEffect(effect = {}, subjectRole = '', objectRole = '') {
+  return effect?.participation?.state === 'active'
+    && effect?.semanticQualification?.state === 'qualified'
+    && effect?.effect === 'declare'
+    && effect?.subjectBinding?.resolvedName === subjectRole
+    && effect?.objectBinding?.resolvedName === objectRole
+    && token(effect?.predicateIdentifier)
+    && token(effect?.predicateMeaning)
+    && effect?.predicateScope === 'local-transition-definition'
+    && effect?.portablePredicateIdentityClaimed === false
+    && ['directed', 'undirected', 'bidirectional'].includes(token(effect?.directionality))
+    && ['pairwise', 'single'].includes(token(effect?.memberMapping?.declared));
+}
+function supportedLocalPlacement(placements = [], destinations = [], output = {}) {
+  const placement = placements[0], destination = destinations[0], 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 exactCount(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.referenceTarget.js

@@ -0,0 +1,50 @@
+import { recoverCanonicalParentReference } from './transition.parentReference.js';
+
+const freeze = Object.freeze;
+
+export function qualifyDurableReferenceParticipant(record = {}, participant = {}, context = {}) {
+  const subjectWorkspaceId = token(context.subjectWorkspaceId);
+  const participantWorkspaceId = token(context.participantWorkspaceId || subjectWorkspaceId);
+  const sameWorkspace = Boolean(subjectWorkspaceId && participantWorkspaceId && subjectWorkspaceId === participantWorkspaceId);
+  if (!record?.id || participant?.cleanCandidate !== true) return unavailable('participant-not-clean');
+
+  const sourceReference = recoverCanonicalParentReference(record, participant);
+  if (sourceReference.state === 'qualified' && sourceReference.representationKind !== 'local-path') {
+    const durable = sourceBackedReference(sourceReference);
+    if (!durable) return unavailable('source-backed-reference-unavailable');
+    return freeze({ state: 'qualified', kind: sourceReference.representationKind, durableTarget: durable, global: true, sameWorkspace, schemaId: participant.candidateSchemaId, recordId: record.id, participantId: participant.identity?.id || '' });
+  }
+
+  if (!sameWorkspace) return unavailable('cross-workspace-local-identity-not-portable');
+  const path = normalizePath(record.path || participant.artifact?.path || '');
+  if (!path) return unavailable('local-path-unavailable');
+  const records = Array.isArray(context.workspaceRecords) ? context.workspaceRecords : [];
+  const collisions = records.filter((item) => normalizePath(item?.path || '') === path);
+  if (collisions.length !== 1 || String(collisions[0]?.id || '') !== String(record.id || '')) return unavailable('local-path-identity-ambiguous');
+  return freeze({ state: 'qualified', kind: 'local-path', durableTarget: path, global: false, sameWorkspace: true, schemaId: participant.candidateSchemaId, recordId: record.id, participantId: participant.identity?.id || '' });
+}
+
+export function referenceTargetOption(record = {}, participant = {}, context = {}) {
+  const qualification = qualifyDurableReferenceParticipant(record, participant, context);
+  return freeze({
+    id: String(record.id || ''),
+    workspaceId: token(context.participantWorkspaceId),
+    title: String(record.title || record.name || participant.artifact?.title || record.path || 'Artifact'),
+    schemaId: token(participant.candidateSchemaId),
+    path: String(record.path || ''),
+    qualification,
+    enabled: qualification.state === 'qualified'
+  });
+}
+
+function sourceBackedReference(reference = {}) {
+  if (reference.representationKind === 'github-issue-embedded' || reference.representationKind === 'github-comment-embedded') {
+    const trace = token(reference.traceTarget);
+    const origin = token(reference.originTarget);
+    return trace && origin ? `${trace} @ ${origin}` : origin || trace;
+  }
+  return token(reference.traceTarget || reference.permalink || reference.originTarget);
+}
+function unavailable(reason) { return freeze({ state: 'unavailable', reason, kind: '', durableTarget: '', global: false, sameWorkspace: false, schemaId: '', recordId: '', participantId: '' }); }
+function normalizePath(value = '') { return String(value || '').trim().replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/{2,}/g, '/'); }
+function token(value = '') { return String(value || '').trim(); }

package/src/transitions/transition.relationMaterializer.js

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