@tiinex/app 0.1.1

package/src/app/appShell.views.jsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import { Button } from '../ui/primitives/Button.jsx';
+import { Modal } from '../ui/primitives/Modal.jsx';
+import { runtime } from './runtimeState.js';
+
+const LOGO_SRC = `${import.meta.env.BASE_URL}assets/tiinex-logo-white-transparent.png`;
+let emptyStageVisitCursor = 0;
+
+export function GlobalDock({ hasWorkspace, workspaceCount, pagerVisible, previousWorkspaceEnabled = true, nextWorkspaceEnabled = true, onPreviousWorkspace, onNextWorkspace, onCreate, homeHref, onShare, onHelp }) {
+  const showPager = Boolean(hasWorkspace && pagerVisible);
+  return (
+    <nav
+      className={`tx-top-dock tx-dock-shell-row ${showPager ? 'tx-top-dock-paged' : 'tx-top-dock-fit'}`}
+      aria-label="Global actions"
+      data-workspace-count={workspaceCount}
+      data-overflow-pager={showPager ? 'visible' : 'hidden'}
+    >
+      {showPager ? <Button shape="round" icon="previous" className="tx-dock-pager-button" aria-label="Previous workspace" disabled={!previousWorkspaceEnabled} onClick={onPreviousWorkspace} /> : null}
+      <span className="tx-dock-core tx-centered-dock-core tx-content-fit-dock tx-poc-brand-first-dock">
+        <a className="tx-logo-command tx-logo-home tx-dock-logo-large" data-home href={homeHref || '/'} aria-label="Tiinex home">
+          <img src={LOGO_SRC} alt="" />
+        </a>
+        <span className="tx-dock-side tx-dock-actions tx-dock-right">
+          <Button icon="create" variant={hasWorkspace ? 'primary' : 'nav'} className="tx-dock-action-button tx-dock-create-button" onClick={onCreate}>Create</Button>
+          <Button icon="shareNodes" variant="nav" className="tx-dock-action-button tx-dock-share-button" onClick={onShare}>Share</Button>
+          <Button icon="help" variant="nav" className="tx-dock-icon-button" aria-label="Help" onClick={onHelp} />
+        </span>
+      </span>
+      {showPager ? <Button shape="round" icon="next" className="tx-dock-pager-button" aria-label="Next workspace" disabled={!nextWorkspaceEnabled} onClick={onNextWorkspace} /> : null}
+    </nav>
+  );
+}
+
+export function EmptyStage({ workspaceConfig }) {
+  const [subtitleCursor] = React.useState(() => emptyStageVisitCursor++);
+  const subtitle = runtime().config?.emptyStageSubtitle?.(workspaceConfig, subtitleCursor) || 'Every handoff starts somewhere';
+  return (
+    <section className="tx-empty-stage tx-old-empty-stage tx-uc001-empty-start tx-m1-product-empty-stage" aria-label="No workspace loaded">
+      <p>{subtitle}</p>
+    </section>
+  );
+}
+
+export function HelpDialog({ workspaceConfig, onDismiss }) {
+  const help = workspaceConfig?.help || [];
+  return (
+    <Modal title="Help" onDismiss={onDismiss}>
+      <div className="tx-help-stack">
+        {help.length ? help.map((item) => (
+          <details key={item.question} open={item.question === 'What is this view?'}>
+            <summary>{item.question}</summary>
+            <p>{item.body}</p>
+          </details>
+        )) : <p className="tx-muted">No workspace help is configured.</p>}
+      </div>
+    </Modal>
+  );
+}

package/src/app/artifactAuthoringCapability.js

@@ -0,0 +1,49 @@
+import { transitionDefinitionsForRecord } from '../transitions/transition.definitions.js';
+import { canDiscardLocalDraft, canEditLocalDraft } from '@tiinex/core/artifacts/artifact.localDraft.js';
+import { durableLocalMutationDecision, DurableLocalMutationOperation } from './durableLocalMutationPolicy.js';
+
+export const ARTIFACT_AUTHORING_CAPABILITY_SCHEMA_ID = 'tiinex.artifact.authoring-capability.v1';
+export const ArtifactAuthoringOperation = Object.freeze({
+  createFromTransition: 'createFromTransition',
+  createRoot: 'createRoot',
+  editLocalDraft: 'editLocalDraft',
+  discardLocalDraft: 'discardLocalDraft'
+});
+
+export function projectArtifactAuthoringCapability(record = {}, options = {}) {
+  const transitions = transitionDefinitionsForRecord(record, options.transitionOptions || {});
+  const createAuthority = durableLocalMutationDecision(options.persistenceOwnership, DurableLocalMutationOperation.localDraftCreate);
+  const discardAuthority = durableLocalMutationDecision(options.persistenceOwnership, DurableLocalMutationOperation.localDraftDelete);
+  const editEligible = canEditLocalDraft(record);
+  const discardEligible = canDiscardLocalDraft(record);
+  return Object.freeze({
+    schema: ARTIFACT_AUTHORING_CAPABILITY_SCHEMA_ID,
+    recordId: String(record?.id || ''),
+    operations: Object.freeze({
+      createFromTransition: operation({
+        available: Boolean(transitions.length && createAuthority.ok),
+        known: Boolean(transitions.length),
+        owner: 'schema-transition/createContinuationDraft',
+        reason: transitions.length ? (createAuthority.ok ? 'Schema-owned transition creation is available.' : createAuthority.notice) : 'No schema-owned authoring transition is available for this artifact.'
+      }),
+      createRoot: operation({ available: false, known: true, owner: 'not-yet-owned', reason: 'Standalone/root artifact creation is not implemented in M4-A.' }),
+      editLocalDraft: operation({
+        available: Boolean(editEligible && createAuthority.ok),
+        known: editEligible,
+        owner: 'local-draft-update-command',
+        reason: !editEligible ? 'Only supported browser-local draft schemas can be edited.' : (createAuthority.ok ? 'This browser-local draft can be edited.' : createAuthority.notice)
+      }),
+      discardLocalDraft: operation({
+        available: Boolean(discardEligible && discardAuthority.ok),
+        known: discardEligible,
+        owner: 'local-draft-discard-command',
+        reason: !discardEligible ? 'Only browser-local drafts can be discarded.' : (discardAuthority.ok ? 'This browser-local draft can be discarded.' : discardAuthority.notice)
+      })
+    }),
+    transitions: Object.freeze(transitions.slice())
+  });
+}
+
+function operation({ available = false, known = false, owner = '', reason = '' } = {}) {
+  return Object.freeze({ available: Boolean(available), known: Boolean(known), owner: String(owner || ''), reason: String(reason || '') });
+}

package/src/app/boot/bootApp.js

@@ -0,0 +1,19 @@
+import { environment } from './environment.js';
+import { schemaRegistry } from '@tiinex/core/schemas/registry.js';
+import { defaultReaderModes } from '../../readers/reader.resolve.js';
+import { surfaceRegistry } from '../../surfaces/registry.js';
+import { auditSeedSummary } from '@tiinex/core/audit/audit.summary.js';
+import { t, defaultLocale } from '../../i18n/i18n.resolve.js';
+
+export function createAppModel() {
+  return {
+    environment,
+    locale: defaultLocale,
+    title: t('app.title'),
+    summary: t('app.summary'),
+    schemas: schemaRegistry,
+    surfaces: surfaceRegistry,
+    readers: defaultReaderModes,
+    audit: auditSeedSummary()
+  };
+}

package/src/app/boot/environment.js

@@ -0,0 +1 @@
+export const environment = Object.freeze({ runtime: 'v82-schema-binding-shell', legacyRuntimeLoaded: false });

package/src/app/canonicalAuthoringValues.js

@@ -0,0 +1,4 @@
+export function canonicalAuthoringSubmissionValues(action = {}, inputValues = {}) {
+  const fixedInputs = action?.authoring?.fixedInputs || {};
+  return Object.freeze({ ...(inputValues || {}), ...fixedInputs });
+}

package/src/app/canonicalCreationProductController.js

@@ -0,0 +1,57 @@
+import { executeCanonicalTransitionLocalCreate } from './canonicalTransitionLocalCreateCommand.js';
+import { executeCanonicalReferenceLocalCreate } from './canonicalReferenceLocalCreateCommand.js';
+import { executeSchemaFactoryLocalCreate } from './schemaFactoryLocalCreateCommand.js';
+import { BUNDLED_CANONICAL_TRANSITION_DEFINITIONS, BUNDLED_CANONICAL_TRANSITION_SCHEMA_CACHE } from '../transitions/canonicalTransition.productDefaults.js';
+import { canonicalCreationProductSettlementState } from './canonicalCreationProductSettlement.js';
+import { isSchemaFactoryViewerCreateAction } from '../schemas/schema.factory.viewerProjection.js';
+
+export function createCanonicalCreationProductController(input = {}) {
+  const executeTransition = input.executeTransitionCommand || executeCanonicalTransitionLocalCreate;
+  const executeReference = input.executeReferenceCommand || executeCanonicalReferenceLocalCreate;
+  const executeFactory = input.executeFactoryCommand || executeSchemaFactoryLocalCreate;
+  const currentState = () => input.getState?.() || {};
+  const lifecycle = () => input.getLifecycle?.() || null;
+  const persistenceOwnership = () => input.getPersistenceOwnership?.() || null;
+  const recordAction = () => input.getRecordAction?.() || null;
+  const dialogWorkspaceId = () => String(input.getDialogWorkspaceId?.() || '');
+
+  function settle(result, workspaceId, action = {}) {
+    input.resetSelection?.();
+    if (action?.productScope === 'workspace') { input.setDialog?.(null); input.setDialogWorkspaceId?.(''); }
+    input.setRecordAction?.(null); input.setActiveRecordId?.(''); input.setActiveAssetId?.(''); input.setNotice?.(result.notice);
+    input.commitSemanticNavigation?.(canonicalCreationProductSettlementState(result, workspaceId, Number(input.viewportWidth || 0)), 'push');
+    return result;
+  }
+
+  function createTransitionRecord(parentRecord, action, values, options = {}) {
+    const sourceState = currentState();
+    const workspaceId = String(options.workspaceId || recordAction()?.workspaceId || dialogWorkspaceId() || sourceState.activeWorkspaceId || '').trim();
+    const result = executeTransition({ lifecycle: lifecycle(), state: sourceState, workspaceId, currentRecordId: parentRecord?.id || '', definitionKey: action?.definitionKey || '', values, placementFolder: options.placementFolder || '', schemaCache: BUNDLED_CANONICAL_TRANSITION_SCHEMA_CACHE, bundledDefinitions: BUNDLED_CANONICAL_TRANSITION_DEFINITIONS, persistenceOwnership: persistenceOwnership() });
+    if (!result?.ok) { input.setNotice?.(result?.notice || 'Could not create canonical local artifact.'); return result; }
+    return settle(result, workspaceId, action);
+  }
+
+  function createFactoryRecord(parentRecord, action, values, options = {}) {
+    const sourceState = currentState();
+    const workspaceId = String(options.workspaceId || dialogWorkspaceId() || sourceState.activeWorkspaceId || '').trim();
+    const result = executeFactory({ lifecycle: lifecycle(), state: sourceState, workspaceId, currentRecordId: parentRecord?.id || '', action, values, placementFolder: options.placementFolder || '', persistenceOwnership: persistenceOwnership() });
+    if (!result?.ok) { input.setNotice?.(result?.notice || 'Could not create schema-factory local artifact.'); return result; }
+    return settle(result, workspaceId, action);
+  }
+
+  function createWorkspaceArtifactRecord(parentRecord, action, values, options = {}) {
+    return isSchemaFactoryViewerCreateAction(action)
+      ? createFactoryRecord(parentRecord, action, values, options)
+      : createTransitionRecord(parentRecord, action, values, options);
+  }
+
+  function createReferenceRecord(subjectRecord, action, targetOption) {
+    const sourceState = currentState();
+    const workspaceId = recordAction()?.workspaceId || sourceState.activeWorkspaceId || '';
+    const result = executeReference({ lifecycle: lifecycle(), state: sourceState, workspaceId, currentRecordId: subjectRecord?.id || '', targetWorkspaceId: targetOption?.workspaceId || '', targetRecordId: targetOption?.id || '', definitionKey: action?.definitionKey || '', schemaCache: BUNDLED_CANONICAL_TRANSITION_SCHEMA_CACHE, bundledDefinitions: BUNDLED_CANONICAL_TRANSITION_DEFINITIONS, persistenceOwnership: persistenceOwnership() });
+    if (!result?.ok) { input.setNotice?.(result?.notice || 'Could not create canonical Reference Relation.'); return result; }
+    return settle(result, workspaceId, action);
+  }
+
+  return Object.freeze({ createTransitionRecord, createFactoryRecord, createWorkspaceArtifactRecord, createReferenceRecord });
+}

package/src/app/canonicalCreationProductSettlement.case.mjs

@@ -0,0 +1,10 @@
+import assert from 'node:assert/strict';
+import { canonicalCreationProductSettlementState } from './canonicalCreationProductSettlement.js';
+const A={id:'A',records:[{id:'subject'},{id:'relation-1'}]}; const B={id:'B',records:[{id:'target'}]};
+const current={activeWorkspaceId:'B',workspaces:[A,B],view:{workspaceVerse:'feed',query:'target'},workspaceViews:{A:{workspaceVerse:'tree',query:'origin',selectedRecordId:'subject'},B:{workspaceVerse:'feed',query:'target',selectedRecordId:'target'}},workspaceWindow:{schema:'tiinex.workspace.window.v1',offset:1}};
+const settled=canonicalCreationProductSettlementState({state:current,workspace:A,record:{id:'relation-1'}},'A',1400);
+assert.equal(settled.activeWorkspaceId,'A','Reference/creation settlement focuses subject/result workspace rather than incidental target workspace');
+assert.equal(settled.view.workspaceVerse,'lineage');
+assert.equal(settled.view.selectedRecordId,'relation-1');
+assert.equal(settled.workspaceViews.B.query,'target','target workspace presentation remains intact');
+console.log('canonicalCreationProductSettlement tests passed');

package/src/app/canonicalCreationProductSettlement.js

@@ -0,0 +1,11 @@
+import { stateWithWorkspaceViewPatchAndFocus } from './workspaceScopedInteraction.js';
+
+export function canonicalCreationProductSettlementState(result = {}, workspaceId = '', viewportWidth = 0) {
+  return stateWithWorkspaceViewPatchAndFocus(result.state || {}, result.workspace?.id || workspaceId, {
+    workspaceVerse: 'lineage',
+    selectedRecordId: result.record?.id || '',
+    lineageQuery: '',
+    lineageLoadReport: null,
+    lineageAuditReport: null
+  }, viewportWidth);
+}

package/src/app/canonicalReferenceLocalCreateCommand.js

@@ -0,0 +1,210 @@
+import { buildCanonicalTransitionInvocationBindingPlan } from '../transitions/transition.invocationBindingPlanner.js';
+import { buildCanonicalTransitionOutputMaterializationPlan } from '../transitions/transition.outputMaterializationPlanner.js';
+import { prepareCanonicalTransitionProductActions } from '../transitions/transition.productPreparation.js';
+import { allocateRootArtifactPath } from '@tiinex/core/transitions/record.transitions.js';
+import { localArtifactMaterializerForSchema } from '../transitions/transition.localArtifactMaterializers.js';
+import { qualifyDurableReferenceParticipant } from '../transitions/transition.referenceTarget.js';
+import { canonicalReferenceTargetOptions, annotatedLoadedRecords } from './canonicalReferenceTargets.js';
+import { durableLocalMutationDecision, DurableLocalMutationOperation } from './durableLocalMutationPolicy.js';
+
+export const CANONICAL_REFERENCE_LOCAL_CREATE_COMMAND_SCHEMA_ID = 'tiinex.site.canonical-reference-local-create-command.v1';
+
+export function executeCanonicalReferenceLocalCreate(input = {}) {
+  const state = input.state || {};
+  const subjectWorkspace = findWorkspace(state, input.workspaceId);
+  if (!subjectWorkspace) return refusal('workspace-not-found', state, 'Reference cannot be created because the subject workspace is unavailable.');
+  const subjectRecord = findRecord(subjectWorkspace, input.currentRecordId);
+  if (!subjectRecord) return refusal('reference-subject-not-found', state, 'Reference cannot be created because the selected subject artifact is unavailable.');
+  const targetWorkspace = findWorkspace(state, input.targetWorkspaceId);
+  const targetRecord = findRecord(targetWorkspace, input.targetRecordId);
+  if (!targetWorkspace || !targetRecord) return refusal('reference-target-not-found', state, 'Reference cannot be created because the selected target artifact is unavailable.');
+  if (subjectWorkspace.id === targetWorkspace.id && subjectRecord.id === targetRecord.id) return refusal('reference-target-not-distinct', state, 'Reference requires a distinct target artifact.');
+
+  const loaded = annotatedLoadedRecords(state);
+  const referenceRecords = loaded.map((item) => item.record);
+  const preparation = prepareCanonicalTransitionProductActions({
+    currentRecord: subjectRecord,
+    workspaceRecords: subjectWorkspace.records || [],
+    referenceRecords,
+    workspaceId: subjectWorkspace.id,
+    schemaCache: input.schemaCache,
+    bundledDefinitions: input.bundledDefinitions
+  });
+  const matches = (preparation.actions || []).filter((candidate) => candidate.definitionKey === input.definitionKey);
+  if (matches.length !== 1) return refusal('canonical-reference-definition-key-not-unique', state, 'Reference cannot be created because the canonical Transition key does not identify exactly one definition.');
+  const action = matches[0];
+  if (!action?.productCapable || action.referenceCapability?.state !== 'qualified') return refusal('canonical-reference-capability-unavailable', state, 'Reference is not qualified for the selected subject artifact.');
+
+  const targets = canonicalReferenceTargetOptions({ state, subjectWorkspaceId: subjectWorkspace.id, subjectRecord, targetSchemaId: action.referenceCapability.targetSchemaId });
+  const targetOption = targets.options.find((option) => option.workspaceId === targetWorkspace.id && option.id === targetRecord.id) || null;
+  if (!targetOption?.enabled) return refusal(targetOption?.qualification?.reason || 'reference-target-identity-unqualified', state, 'Reference target does not have durable enough identity for this bounded product capability.', { targetQualification: targetOption?.qualification || null });
+  if (!(action.referenceCapability.targetCandidateParticipantIds || []).includes(targetOption.participantId)) return refusal('reference-target-not-applicable', state, 'Reference target does not satisfy the exact Transition target role.');
+
+  const subjectParticipant = targets.subjectParticipant;
+  const subjectQualification = qualifyDurableReferenceParticipant(subjectRecord, subjectParticipant, {
+    subjectWorkspaceId: subjectWorkspace.id,
+    participantWorkspaceId: subjectWorkspace.id,
+    workspaceRecords: subjectWorkspace.records || []
+  });
+  if (subjectQualification.state !== 'qualified') return refusal(subjectQualification.reason || 'reference-subject-identity-unqualified', state, 'Reference subject does not have durable enough identity for this bounded product capability.', { subjectQualification });
+
+  const result = action.resultSemantics || {};
+  const output = result.outputRoles?.[0];
+  const outputSchemaId = token(output?.schemaConstraint);
+  const materializer = localArtifactMaterializerForSchema(outputSchemaId);
+  if (!materializer || outputSchemaId !== 'tiinex.relation.v1') return refusal('canonical-reference-materializer-unavailable', state, 'Reference Relation materializer is unavailable for the exact qualified output schema.');
+  const relation = action.referenceCapability.relationEffect || {};
+  const placement = result.outputPlacements?.[0] || {};
+  const destination = result.destinationBindings?.[0] || {};
+  const explicit = action.explicitGenerationQualification || null;
+  const outputRole = token(action.referenceCapability.outputRole || output?.name);
+  if (token(explicit?.qualification) !== 'qualified') return refusal('explicit-generation-authority-unqualified', state, 'Reference Relation generation authority is not exactly qualified.');
+
+  const relationTitle = `Reference ${subjectRecord.title || 'Topic'} to ${targetRecord.title || 'Task'}`;
+  const packet = {
+    inputRoles: [
+      { role: action.referenceCapability.subjectRole, members: [{ bindingId: 'reference-subject-1', participantId: subjectParticipant.identity.id }] },
+      { role: action.referenceCapability.targetRole, members: [{ bindingId: 'reference-target-1', participantId: targetOption.participantId }] }
+    ],
+    destinations: [{ name: destination.name || '', value: subjectWorkspace.id }],
+    naming: [{ placement: placement.name || '', value: relationTitle }],
+    memberAssociations: []
+  };
+  const bindingPlan = buildCanonicalTransitionInvocationBindingPlan({
+    definition: action.definition,
+    participantIndex: targets.participantIndex,
+    currentArtifact: subjectParticipant,
+    bindingPacket: packet
+  });
+
+  const values = referenceGenerationValues({ action, subjectQualification, targetQualification: targetOption.qualification });
+  const requiredInputNames = (explicit.authority?.requiredInputs || []).map((item) => token(item?.name)).filter(Boolean);
+  if (!requiredInputNames.length || requiredInputNames.some((name) => !token(values[name]))) return refusal('reference-generation-values-incomplete', state, 'Reference Relation generation values are incomplete for the exact generation authority.', { values });
+  const generationInputs = requiredInputNames.map((name) => ({ outputRole, name, value: values[name] }));
+  const v423 = buildCanonicalTransitionOutputMaterializationPlan({
+    definition: action.definition,
+    participantIndex: targets.participantIndex,
+    currentArtifact: subjectParticipant,
+    bindingPacket: packet,
+    generationInputs,
+    explicitGenerationAuthorities: [{ outputRole, qualification: explicit }]
+  });
+  if (bindingPlan.qualification !== 'qualified' || v423.qualification !== 'qualified') return refusal('canonical-reference-plan-not-qualified', state, 'Reference cannot be created because canonical binding/materialization planning did not qualify.', { bindingPlan, v423 });
+
+  const capability = referenceExecutionCapability({ action, v423, subjectWorkspace, targetOption, materializer });
+  if (!capability.ok) return refusal(capability.error, state, capability.notice, { bindingPlan, v423, capability });
+
+  const allocation = allocateRootArtifactPath({ targetId: outputSchemaId, targetLabel: materializer.label, title: relationTitle }, { workspaceRecords: subjectWorkspace.records || [] });
+  const concretePath = token(allocation.path);
+  if (!concretePath) return refusal('reference-local-path-allocation-unavailable', state, 'Reference Relation cannot be created because a browser-local path could not be allocated.', { bindingPlan, v423 });
+  const cacheById = Object.fromEntries((preparation.cacheQualification?.entries || []).map((item) => [item.schemaId, item]));
+  const relationSchemaMaterials = [cacheById['tiinex.root.v1']?.markdown || '', cacheById[outputSchemaId]?.markdown || ''];
+  const rendered = materializer.render({ values, parent: null, continuityMode: 'root', now: input.now });
+  if (rendered.state !== 'rendered') return refusal(rendered.reason, state, 'Reference Relation could not be rendered from its qualified generation values.', { bindingPlan, v423 });
+  const artifactQualification = materializer.qualify({ markdown: rendered.markdown, schemaMaterials: relationSchemaMaterials, values, parent: null, continuityMode: 'root', path: concretePath });
+  if (artifactQualification.state !== 'qualified') return refusal(artifactQualification.reason, state, 'Reference Relation did not satisfy the exact Relation contract.', { bindingPlan, v423, artifactQualification });
+
+  const authority = durableLocalMutationDecision(input.persistenceOwnership, DurableLocalMutationOperation.localDraftCreate);
+  if (!authority.ok) return refusal(authority.error || 'local-mutation-not-authorized', state, authority.notice || 'Local Reference creation is not available in this session.', { bindingPlan, v423, artifactQualification });
+  if (!input.lifecycle?.addWorkspaceRecord) return refusal('workspace-lifecycle-unavailable', state, 'Reference Relation cannot be created because the local workspace lifecycle is unavailable.');
+  const beforeSubject = stableJson(subjectRecord), beforeTarget = stableJson(targetRecord);
+  const candidate = Object.assign({}, artifactQualification.record, {
+    sourceMode: 'local-transition-canonical',
+    path: concretePath,
+    transitionMaterialization: {
+      schema: CANONICAL_REFERENCE_LOCAL_CREATE_COMMAND_SCHEMA_ID,
+      canonicalIdentifier: action.canonicalIdentifier,
+      remoteWrite: false,
+      sourceMutation: false,
+      targetMutation: false,
+      concretePath,
+      continuityMode: 'root',
+      relationMaterialization: true
+    }
+  });
+  delete candidate.source;
+  delete candidate.sourceTarget;
+  const committed = input.lifecycle.addWorkspaceRecord(state, subjectWorkspace.id, candidate, { clock: input.clock });
+  if (!committed?.ok) return refusal(committed?.error || 'workspace-mutation-failed', state, 'Reference Relation could not be added to the browser-local workspace.', { bindingPlan, v423, artifactQualification });
+
+  const afterSubject = findRecord(findWorkspace(committed.state, subjectWorkspace.id), subjectRecord.id);
+  const afterTarget = findRecord(findWorkspace(committed.state, targetWorkspace.id), targetRecord.id);
+  if (stableJson(afterSubject) !== beforeSubject || stableJson(afterTarget) !== beforeTarget) return refusal('post-mutation-participant-boundary-violation', state, 'Reference creation was refused because a participant artifact changed.', { bindingPlan, v423, artifactQualification });
+  const createdSource = committed.record?.source || {};
+  if (createdSource.adapterId === 'github' || createdSource.repository || createdSource.repo || createdSource.ref || committed.record?.sourceTarget) return refusal('post-mutation-source-boundary-violation', state, 'Reference Relation inherited source provenance and was refused.', { bindingPlan, v423, artifactQualification });
+
+  return Object.freeze({
+    ok: true,
+    schema: CANONICAL_REFERENCE_LOCAL_CREATE_COMMAND_SCHEMA_ID,
+    state: committed.state,
+    workspace: committed.workspace,
+    record: committed.record,
+    subjectRecord,
+    targetRecord,
+    subjectQualification,
+    targetQualification: targetOption.qualification,
+    bindingPlan,
+    v423,
+    artifactQualification,
+    concretePath,
+    relationMaterialization: true,
+    remoteWrite: false,
+    sourceMutation: false,
+    targetMutation: false,
+    notice: `Created local Reference Relation from ${subjectRecord.title || 'subject'} to ${targetRecord.title || 'target'}.`
+  });
+}
+
+function referenceGenerationValues({ action = {}, subjectQualification = {}, targetQualification = {} } = {}) {
+  const effect = action.referenceCapability?.relationEffect || {};
+  const transitionPath = token(action.definition?.artifact?.path || action.definition?.artifact?.source?.sourceArtifactPath);
+  const generationTarget = token(action.explicitGenerationQualification?.resolution?.target);
+  const exact = action.explicitGenerationQualification?.exactAuthorityRepresentations || {};
+  return Object.freeze({
+    'Relation Type': 'topic reference to task',
+    'Relation Direction': 'Topic subject -> referenced Task',
+    'Relation Scope': 'artifact-level',
+    'Relation Target': token(targetQualification.durableTarget),
+    'Predicate Identifier': token(effect.predicateIdentifier),
+    'Predicate Meaning': token(effect.predicateMeaning),
+    'Subject Binding': token(subjectQualification.durableTarget),
+    'Object Binding': token(targetQualification.durableTarget),
+    Directionality: token(effect.directionality),
+    'Transition Authority': transitionPath ? `site-local:${transitionPath}` : '',
+    'Transition Authority Representation Method': token(exact.transition?.method),
+    'Transition Authority Representation Value': token(exact.transition?.value),
+    'Generation Authority': generationTarget,
+    'Generation Authority Representation Method': token(exact.generation?.method),
+    'Generation Authority Representation Value': token(exact.generation?.value)
+  });
+}
+function referenceExecutionCapability({ action = {}, v423 = {}, subjectWorkspace = {}, targetOption = {}, materializer = null } = {}) {
+  const output = v423.outputRolePlans?.[0] || {};
+  const placement = output.placements?.[0] || {};
+  const effect = action.referenceCapability?.relationEffect || {};
+  const supported = v423.outputRolePlans?.length === 1
+    && output.outputCount?.exactCount === 1
+    && output.effectiveParticipantKind === 'artifact'
+    && output.schemaConstraint === 'tiinex.relation.v1'
+    && output.generation?.authority === 'explicit-reference'
+    && output.generation?.state === 'resolved'
+    && output.lifecycle?.requestedOperation === 'create'
+    && placement.placementIntent === 'new-materialization'
+    && placement.destinationValue === subjectWorkspace.id
+    && placement.naming?.authority === 'explicit-binding'
+    && placement.naming?.state === 'resolved'
+    && placement.concretePath === null
+    && action.resultSemantics?.parentEffects?.length === 0
+    && action.resultSemantics?.relationEffects?.length === 1
+    && effect.semanticQualification?.state === 'qualified'
+    && effect.predicateScope === 'local-transition-definition'
+    && effect.portablePredicateIdentityClaimed === false
+    && targetOption.enabled === true
+    && materializer?.schemaId === 'tiinex.relation.v1';
+  return Object.freeze({ ok: Boolean(supported), error: supported ? '' : 'canonical-reference-pattern-unsupported', notice: supported ? '' : 'Reference is outside the bounded durable browser-local capability.' });
+}
+function findWorkspace(state = {}, id = '') { const key = token(id); return (state.workspaces || []).find((item) => token(item?.id) === key) || null; }
+function findRecord(workspace = null, id = '') { const key = token(id); return (workspace?.records || []).find((item) => token(item?.id) === key) || null; }
+function refusal(error, state, notice, extra = {}) { return Object.freeze({ ok: false, schema: CANONICAL_REFERENCE_LOCAL_CREATE_COMMAND_SCHEMA_ID, error, state, notice, ...extra, remoteWrite: false, sourceMutation: false, targetMutation: false, relationMaterialization: false, concretePath: null }); }
+function stableJson(value) { return JSON.stringify(value ?? null); }
+function token(value = '') { return String(value || '').trim(); }

package/src/app/canonicalReferenceTargets.js

@@ -0,0 +1,73 @@
+import { buildLoadedArtifactParticipantIndex, participantMatchesSchema, resolveCurrentArtifactParticipant } from '../artifacts/artifact.participantIndex.js';
+import { referenceTargetOption } from '../transitions/transition.referenceTarget.js';
+
+export const CANONICAL_REFERENCE_TARGET_OPTIONS_SCHEMA_ID = 'tiinex.site.canonical-reference-target-options.v1';
+
+export function canonicalReferenceTargetOptions(input = {}) {
+  const state = input.state || {};
+  const subjectWorkspaceId = token(input.subjectWorkspaceId);
+  const subjectRecord = input.subjectRecord || null;
+  const targetSchemaId = token(input.targetSchemaId);
+  const loaded = annotatedLoadedRecords(state);
+  const participantIndex = buildLoadedArtifactParticipantIndex({ records: loaded.map((item) => item.record) });
+  const subjectAnnotated = loaded.find((item) => item.workspaceId === subjectWorkspaceId && String(item.record?.id || '') === String(subjectRecord?.id || ''))?.record || subjectRecord;
+  const subjectParticipant = resolveCurrentArtifactParticipant(subjectAnnotated, participantIndex);
+  if (!subjectParticipant?.cleanCandidate || !targetSchemaId) return result([], participantIndex, subjectParticipant, 'subject-or-target-schema-unqualified');
+
+  const byParticipant = new Map();
+  for (const item of loaded) {
+    const participant = resolveCurrentArtifactParticipant(item.record, participantIndex);
+    if (!participantMatchesSchema(participant, targetSchemaId)) continue;
+    if (participant.identity?.id === subjectParticipant.identity?.id) continue;
+    const option = referenceTargetOption(item.original, participant, {
+      subjectWorkspaceId,
+      participantWorkspaceId: item.workspaceId,
+      workspaceRecords: item.workspaceRecords
+    });
+    const key = token(participant.identity?.id);
+    if (!key) continue;
+    const previous = byParticipant.get(key);
+    if (!previous || preferOption(option, previous, subjectWorkspaceId)) byParticipant.set(key, Object.freeze({ ...option, key: `participant:${key}`, participantId: key }));
+  }
+  const options = [...byParticipant.values()].sort(compareOptions);
+  return result(options, participantIndex, subjectParticipant, 'qualified');
+}
+
+export function annotatedLoadedRecords(state = {}) {
+  const out = [];
+  for (const workspace of Array.isArray(state.workspaces) ? state.workspaces : []) {
+    const workspaceId = token(workspace?.id);
+    const records = Array.isArray(workspace?.records) ? workspace.records : [];
+    for (const original of records) {
+      const workspaceIds = [...new Set([...(Array.isArray(original?.workspaceIds) ? original.workspaceIds : []), workspaceId].map(token).filter(Boolean))].sort();
+      out.push(Object.freeze({ workspaceId, workspaceRecords: records, original, record: Object.freeze({ ...original, workspaceIds }) }));
+    }
+  }
+  return Object.freeze(out);
+}
+
+function result(options, participantIndex, subjectParticipant, state) {
+  return Object.freeze({
+    schema: CANONICAL_REFERENCE_TARGET_OPTIONS_SCHEMA_ID,
+    state,
+    options: Object.freeze(options),
+    qualifiedOptions: Object.freeze(options.filter((item) => item.enabled)),
+    unavailableOptions: Object.freeze(options.filter((item) => !item.enabled)),
+    participantIndex,
+    subjectParticipant: subjectParticipant || null,
+    readOnly: true,
+    mutation: false,
+    networkFetch: false
+  });
+}
+function preferOption(next, previous, subjectWorkspaceId) {
+  if (next.enabled !== previous.enabled) return next.enabled;
+  const nextSame = next.workspaceId === subjectWorkspaceId, previousSame = previous.workspaceId === subjectWorkspaceId;
+  if (nextSame !== previousSame) return nextSame;
+  return `${next.workspaceId}\0${next.id}`.localeCompare(`${previous.workspaceId}\0${previous.id}`) < 0;
+}
+function compareOptions(a, b) {
+  if (a.enabled !== b.enabled) return a.enabled ? -1 : 1;
+  return String(a.title || '').localeCompare(String(b.title || '')) || String(a.workspaceId || '').localeCompare(String(b.workspaceId || '')) || String(a.id || '').localeCompare(String(b.id || ''));
+}
+function token(value = '') { return String(value || '').trim(); }