@tiinex/app 0.1.1

package/src/app/canonicalTransitionLocalCreateCommand.js

@@ -0,0 +1,217 @@
+import { buildCanonicalTransitionInvocationBindingPlan } from '../transitions/transition.invocationBindingPlanner.js';
+import { buildCanonicalTransitionOutputMaterializationPlan } from '../transitions/transition.outputMaterializationPlanner.js';
+import { finalizeCanonicalParentReference, prepareCanonicalTransitionProductActions, prepareCanonicalTransitionWorkspaceActions } from '../transitions/transition.productPreparation.js';
+import { allocateContinuationPath, allocateRootArtifactPath } from '@tiinex/core/transitions/record.transitions.js';
+import { localArtifactMaterializerForSchema } from '../transitions/transition.localArtifactMaterializers.js';
+import { durableLocalMutationDecision, DurableLocalMutationOperation } from './durableLocalMutationPolicy.js';
+import { canonicalAuthoringSubmissionValues } from './canonicalAuthoringValues.js';
+import { explicitPlacementPath } from './workspacePlacementOptions.js';
+
+export const CANONICAL_TRANSITION_LOCAL_CREATE_COMMAND_SCHEMA_ID = 'tiinex.site.canonical-transition-local-create-command.v1';
+
+export function executeCanonicalTransitionLocalCreate(input = {}) {
+  const state = input.state || {};
+  const workspace = (state.workspaces || []).find((item) => item.id === input.workspaceId);
+  if (!workspace) return refusal('workspace-not-found', state, 'Artifact cannot be created because the target workspace is unavailable.');
+
+  const requestedRecordId = String(input.currentRecordId || '').trim();
+  const currentRecord = requestedRecordId ? (workspace.records || []).find((item) => item.id === requestedRecordId) : null;
+  if (requestedRecordId && !currentRecord) return refusal('source-record-not-found', state, 'Artifact cannot be created because the selected source artifact is unavailable.');
+  const beforeSource = currentRecord ? stableJson(currentRecord) : '';
+
+  const preparation = currentRecord
+    ? prepareCanonicalTransitionProductActions({
+      currentRecord,
+      workspaceRecords: workspace.records || [],
+      workspaceId: workspace.id,
+      schemaCache: input.schemaCache,
+      bundledDefinitions: input.bundledDefinitions
+    })
+    : prepareCanonicalTransitionWorkspaceActions({
+      workspaceId: workspace.id,
+      schemaCache: input.schemaCache,
+      bundledDefinitions: input.bundledDefinitions
+    });
+  const actionMatches = (preparation.actions || []).filter((candidate) => candidate.definitionKey === input.definitionKey);
+  if (actionMatches.length !== 1) return refusal('canonical-definition-key-not-unique', state, 'Artifact cannot be created because the canonical Transition execution key does not identify exactly one definition.');
+  const action = actionMatches[0];
+  if (!action?.productCapable) return refusal('canonical-create-capability-unavailable', state, productFailureNotice(action));
+
+  const continuityMode = action.continuityMode === 'root' ? 'root' : 'parent';
+  if (continuityMode === 'root' && currentRecord) return refusal('canonical-root-create-source-unexpected', state, 'Standalone artifact creation cannot bind a selected source artifact.');
+  if (continuityMode === 'parent' && !currentRecord) return refusal('canonical-parent-create-source-required', state, 'Continuation artifact creation requires the selected source artifact.');
+
+  const definition = action.definition;
+  const result = action.resultSemantics;
+  const output = result.outputRoles?.[0];
+  const outputSchemaId = String(output?.schemaConstraint || '').trim();
+  const materializer = localArtifactMaterializerForSchema(outputSchemaId);
+  if (!materializer) return refusal('canonical-local-materializer-unavailable', state, `No qualified browser-local materializer is available for ${outputSchemaId || 'this output schema'}.`);
+  const parentEffect = result.parentEffects?.[0] || null;
+  const placement = result.outputPlacements?.[0];
+  const destination = result.destinationBindings?.[0];
+  const sourceRole = parentEffect?.parentBinding?.resolvedName || '';
+  const values = canonicalAuthoringSubmissionValues(action, input.values || {});
+  const outputTitle = canonicalOutputTitle(action, values, materializer.label);
+  const packet = {
+    inputRoles: continuityMode === 'parent'
+      ? [{ role: sourceRole, members: [{ bindingId: 'current-artifact-1', participantId: action.currentParticipant?.identity?.id || '' }] }]
+      : [],
+    destinations: [{ name: destination?.name || '', value: workspace.id }],
+    naming: [{ placement: placement?.name || '', value: outputTitle }],
+    memberAssociations: []
+  };
+  const bindingPlan = buildCanonicalTransitionInvocationBindingPlan({
+    definition,
+    participantIndex: preparation.participantIndex,
+    currentArtifact: action.currentParticipant,
+    bindingPacket: packet
+  });
+  const generationInputs = (action.authoring?.requiredInputs || []).map((name) => ({ outputRole: output?.name || '', name, value: values[name] }));
+  const schemaById = Object.fromEntries((preparation.cacheQualification?.entries || []).map((item) => [item.schemaId, item]));
+  const targetSchemaMaterials = [schemaById['tiinex.root.v1']?.markdown || '', schemaById[outputSchemaId]?.markdown || ''];
+  const targetSchemaAuthorities = [{ outputRole: output?.name || '', materials: targetSchemaMaterials }];
+  const v423 = buildCanonicalTransitionOutputMaterializationPlan({
+    definition,
+    participantIndex: preparation.participantIndex,
+    currentArtifact: action.currentParticipant,
+    bindingPacket: packet,
+    generationInputs,
+    targetSchemaAuthorities
+  });
+  if (bindingPlan.qualification !== 'qualified' || v423.qualification !== 'qualified') {
+    return refusal(
+      v423.qualification === 'incomplete' ? 'canonical-create-input-incomplete' : 'canonical-create-plan-not-qualified',
+      state,
+      v423.qualification === 'incomplete' ? `Complete every required ${materializer.label} field before creating the local artifact.` : `${materializer.label} cannot be created because its canonical Transition plan is not fully qualified.`,
+      { bindingPlan, v423 }
+    );
+  }
+
+  const capability = executionCapability({ action, v423, workspace, outputSchemaId, materializer, continuityMode });
+  if (!capability.ok) return refusal(capability.error, state, capability.notice, { bindingPlan, v423, capability });
+
+  const automaticAllocation = continuityMode === 'root'
+    ? allocateRootArtifactPath({ targetId: outputSchemaId, targetLabel: materializer.label, title: outputTitle }, { workspaceRecords: workspace.records || [] })
+    : allocateContinuationPath({ parentRecord: currentRecord, targetId: outputSchemaId, targetLabel: materializer.label, title: outputTitle }, { workspaceRecords: workspace.records || [] });
+  const placementFolder = String(input.placementFolder || '').trim();
+  const requestedPath = placementFolder ? explicitPlacementPath(automaticAllocation.path, placementFolder) : '';
+  const allocation = requestedPath
+    ? (continuityMode === 'root'
+      ? allocateRootArtifactPath({ targetId: outputSchemaId, targetLabel: materializer.label, title: outputTitle }, { workspaceRecords: workspace.records || [], path: requestedPath })
+      : allocateContinuationPath({ parentRecord: currentRecord, targetId: outputSchemaId, targetLabel: materializer.label, title: outputTitle }, { workspaceRecords: workspace.records || [], path: requestedPath }))
+    : automaticAllocation;
+  const concretePath = allocation.path || '';
+  if (!concretePath) return refusal('canonical-local-path-allocation-unavailable', state, `${materializer.label} cannot be created because its browser-local path could not be allocated.`, { bindingPlan, v423 });
+
+  const parent = continuityMode === 'root' ? null : finalizeCanonicalParentReference(action.parentRecovery, concretePath);
+  if (continuityMode === 'parent' && (parent?.state !== 'qualified' || parent?.finalized !== true)) {
+    return refusal(parent?.reason || 'canonical-parent-finalization-unavailable', state, `${materializer.label} cannot be created because its Parent reference could not be finalized truthfully.`, { bindingPlan, v423 });
+  }
+  const rendered = materializer.render({ values, parent, continuityMode, now: input.now });
+  if (rendered.state !== 'rendered') return refusal(rendered.reason, state, `${materializer.label} could not be rendered from the qualified canonical creation values.`, { bindingPlan, v423 });
+  const artifactQualification = materializer.qualify({ markdown: rendered.markdown, schemaMaterials: targetSchemaMaterials, values, parent, continuityMode, path: concretePath });
+  if (artifactQualification.state !== 'qualified') return refusal(artifactQualification.reason, state, `${materializer.label} could not be created because the rendered Artifact did not satisfy its canonical schema contract.`, { bindingPlan, v423, artifactQualification, taskQualification: artifactQualification });
+
+  const authority = durableLocalMutationDecision(input.persistenceOwnership, DurableLocalMutationOperation.localDraftCreate);
+  if (!authority.ok) return refusal(authority.error || 'local-mutation-not-authorized', state, authority.notice || `Local ${materializer.label} creation is not available in this session.`, { bindingPlan, v423, artifactQualification, taskQualification: artifactQualification, authority });
+  if (!input.lifecycle?.addWorkspaceRecord) return refusal('workspace-lifecycle-unavailable', state, `${materializer.label} cannot be created because the local workspace lifecycle is unavailable.`);
+  const candidate = Object.assign({}, artifactQualification.record, {
+    sourceMode: 'local-transition-canonical',
+    path: concretePath,
+    transitionMaterialization: {
+      schema: CANONICAL_TRANSITION_LOCAL_CREATE_COMMAND_SCHEMA_ID,
+      canonicalIdentifier: action.canonicalIdentifier,
+      remoteWrite: false,
+      sourceMutation: false,
+      concretePath,
+      continuityMode,
+      relationMaterialization: false,
+      placement: Object.freeze({ mode: placementFolder ? 'explicit-same-workspace-folder' : 'automatic', folder: placementFolder, path: concretePath })
+    }
+  });
+  delete candidate.source;
+  delete candidate.sourceTarget;
+  const committed = input.lifecycle.addWorkspaceRecord(state, workspace.id, candidate, { clock: input.clock });
+  if (!committed?.ok) return refusal(committed?.error || 'workspace-mutation-failed', state, `${materializer.label} could not be added to the browser-local workspace.`, { bindingPlan, v423, artifactQualification, taskQualification: artifactQualification });
+
+  if (currentRecord) {
+    const afterSource = (committed.workspace?.records || []).find((item) => item.id === currentRecord.id);
+    if (stableJson(afterSource) !== beforeSource) {
+      return refusal('post-mutation-source-boundary-violation', state, `${materializer.label} creation was refused because the selected source artifact boundary did not remain isolated.`, { bindingPlan, v423, artifactQualification, taskQualification: 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, `${materializer.label} creation was refused because the browser-local artifact inherited source provenance.`, { bindingPlan, v423, artifactQualification, taskQualification: artifactQualification });
+  }
+
+  return Object.freeze({
+    ok: true,
+    schema: CANONICAL_TRANSITION_LOCAL_CREATE_COMMAND_SCHEMA_ID,
+    state: committed.state,
+    workspace: committed.workspace,
+    record: committed.record,
+    bindingPlan,
+    v423,
+    artifactQualification,
+    taskQualification: artifactQualification,
+    remoteWrite: false,
+    sourceMutation: false,
+    concretePath,
+    continuityMode,
+    relationMaterialization: false,
+    placement: Object.freeze({ mode: placementFolder ? 'explicit-same-workspace-folder' : 'automatic', folder: placementFolder, path: concretePath }),
+    notice: continuityMode === 'root'
+      ? `Created standalone local ${materializer.label} in ${workspace.name || workspace.title || 'workspace'}.`
+      : `Created local ${materializer.label} from ${currentRecord.title || 'selected artifact'}.`
+  });
+}
+
+function executionCapability({ action, v423, workspace, outputSchemaId, materializer, continuityMode = 'parent' }) {
+  const output = v423.outputRolePlans?.[0];
+  const lifecycle = output?.lifecycle || {};
+  const placement = output?.placements?.[0] || {};
+  const parent = action.resultSemantics?.parentEffects?.[0] || null;
+  const inputRole = (action.availability?.inputRoles || []).find((role) => role.name === parent?.parentBinding?.resolvedName);
+  const inputSchemaId = String(inputRole?.schemaConstraint || '').trim();
+  const common = v423.outputRolePlans?.length === 1
+    && output?.outputCount?.exactCount === 1
+    && output?.effectiveParticipantKind === 'artifact'
+    && output?.schemaConstraint === outputSchemaId
+    && materializer?.schemaId === outputSchemaId
+    && output?.generation?.authority === 'target-schema'
+    && output?.generation?.state === 'resolved'
+    && lifecycle.requestedOperation === 'create'
+    && placement.placementIntent === 'new-materialization'
+    && placement.destinationValue === workspace.id
+    && placement.naming?.authority === 'explicit-binding'
+    && placement.naming?.state === 'resolved'
+    && placement.concretePath === null
+    && action.resultSemantics?.relationEffects?.length === 0;
+  const continuity = continuityMode === 'root'
+    ? action.resultSemantics?.parentEffects?.length === 0 && (action.availability?.inputRoles || []).length === 0 && !action.currentParticipant
+    : parent?.effect === 'set'
+      && parent?.parentBinding?.qualification === 'resolved'
+      && Boolean(inputSchemaId)
+      && action.parentRecovery?.state === 'qualified'
+      && action.parentRecovery?.schemaId === inputSchemaId;
+  const supported = Boolean(common && continuity);
+  return Object.freeze({ ok: supported, error: supported ? '' : 'canonical-local-create-pattern-unsupported', notice: supported ? '' : `${materializer?.label || 'Artifact'} cannot be created because this canonical Transition is outside the supported browser-local create capability.` });
+}
+
+function canonicalOutputTitle(action = {}, values = {}, fallback = 'Artifact') {
+  const summary = String(values.Summary || '').trim();
+  if (summary) return summary;
+  const targetRole = String(values['Target Role'] || '').trim();
+  const interpretationAction = String(values['Interpretation Action'] || '').trim();
+  if (targetRole || interpretationAction) return `${interpretationAction || action.label || 'Use as'} ${targetRole || fallback}`.trim();
+  return String(action.label || fallback || 'Artifact').trim() || 'Artifact';
+}
+function productFailureNotice(action) {
+  const label = action?.authoring?.schemaLabel || 'Artifact';
+  if (action?.continuityMode !== 'root' && action?.parentRecovery?.state !== 'qualified') return `${label} cannot be created because the selected source artifact cannot be referenced safely.`;
+  return `${label} cannot be created because the canonical Transition is not currently product-capable.`;
+}
+function refusal(error, state, notice, extra = {}) { return Object.freeze({ ok: false, schema: CANONICAL_TRANSITION_LOCAL_CREATE_COMMAND_SCHEMA_ID, error, state, notice, ...extra, remoteWrite: false, sourceMutation: false, concretePath: null, relationMaterialization: false }); }
+function stableJson(value) { return JSON.stringify(value ?? null); }

package/src/app/defaultWorkspaceStart.case.mjs

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import '../workspaces/workspace.config.js';
+import { DEFAULT_WORKSPACE_START_CONFIG_URL, defaultWorkspaceStartPlan, stateWithDefaultWorkspaceStartProgress } from './defaultWorkspaceStart.js';
+
+const config = globalThis.TiinexWorkspaceConfig.createDefaultWorkspaceConfig();
+const plan = defaultWorkspaceStartPlan(config);
+
+assert.equal(plan.ok, true, plan.message);
+assert.equal(plan.input.appConfigSourceUrl, DEFAULT_WORKSPACE_START_CONFIG_URL);
+assert.equal(plan.input.bootstrapStartState, 'default-workspace-config');
+assert.equal(plan.input.bootstrapBoundary, 'explicit-default-config-path');
+assert.equal(plan.input.repository, 'Tiinex/docs');
+assert.equal(plan.input.rootPath, '.topics');
+assert.equal(plan.input.repoDiscovery, true);
+assert.equal(plan.selectedPlan, 'workspace-entrypoints', 'PoC startup applies Workspace Entrypoints as the initial workspace set');
+assert.equal(plan.input.issueDiscovery, true, 'default entrypoint preserves its configured issue discovery surface');
+assert.equal(plan.input.workspaceMatch, '', 'Workspace Discovery chooser is not the initial workspace owner when entrypoints exist');
+assert.equal(plan.input.preserveView, false);
+assert.equal(plan.input.preferredDisplay, '');
+assert.match(plan.workspaceName, /Tiinex docs/i);
+
+
+
+const stateWithShell = {
+  activeWorkspaceId: 'ws-default',
+  workspaces: [{ id: 'ws-default', title: 'Tiinex docs', sources: [], records: [] }]
+};
+const queued = stateWithDefaultWorkspaceStartProgress(stateWithShell, 'ws-default', plan);
+assert.equal(queued.activeWorkspaceId, 'ws-default');
+assert.equal(queued.workspaces[0].discoveryProgress.phase, 'default-workspace-bootstrap');
+assert.equal(queued.workspaces[0].discoveryProgress.active, true, 'default start must make the clean shell visibly loading before source materialization finishes');
+assert.equal(queued.workspaces[0].workspaceBootstrap.boundary, 'explicit-default-config-path');
+assert.equal(queued.workspaces[0].workspaceBootstrap.usefulStartPath, 'explicit-source-materialization-queued');
+assert.equal(stateWithShell.workspaces[0].discoveryProgress, undefined, 'progress helper must not mutate input state');
+
+const empty = defaultWorkspaceStartPlan({ workspaceEntrypoints: [], workspaceDiscovery: [], viewerIdentity: { browserTitle: 'Empty' } });
+assert.equal(empty.ok, false, 'empty config must not invent a default GitHub source');
+
+console.log('✓ default workspace start plan tests passed');

package/src/app/defaultWorkspaceStart.js

@@ -0,0 +1,65 @@
+import { tiinexAppConfigSourceToStartupPlan } from './tiinexAppConfigSource.js';
+
+export const DEFAULT_WORKSPACE_START_CONFIG_URL = 'embedded-default-workspace';
+export const DEFAULT_WORKSPACE_START_ID = 'workspace:embedded-default:tiinex-docs';
+
+export function defaultWorkspaceStartPlan(workspaceConfig = {}) {
+  const mapped = tiinexAppConfigSourceToStartupPlan({
+    config: workspaceConfig,
+    configUrl: DEFAULT_WORKSPACE_START_CONFIG_URL,
+    diagnostics: { selectedConvention: 'embedded-default-workspace' }
+  });
+  if (!mapped?.ok) {
+    return {
+      ok: false,
+      message: mapped?.message || 'Default Tiinex workspace config has no explicit source or discovery path.'
+    };
+  }
+  const inputs = (mapped.inputs || [mapped.input]).filter(Boolean).map((item) => Object.assign({}, item, {
+    appConfigSourceUrl: item.appConfigSourceUrl || DEFAULT_WORKSPACE_START_CONFIG_URL,
+    bootstrapStartState: 'default-workspace-config',
+    bootstrapBoundary: 'explicit-default-config-path'
+  }));
+  const input = inputs[0];
+  const identity = workspaceConfig?.viewerIdentity || {};
+  const workspaceName = input?.label || identity.browserTitle || 'Tiinex docs';
+  return {
+    ok: true,
+    workspaceName,
+    selectedPlan: mapped.selectedPlan || 'workspace-entrypoints',
+    input,
+    inputs,
+    message: inputs.length > 1 ? `Opening ${inputs.length} configured workspaces.` : `Opening ${workspaceName} workspace.`
+  };
+}
+
+
+export function stateWithDefaultWorkspaceStartProgress(state = {}, workspaceId = '', plan = {}) {
+  const targetId = String(workspaceId || '').trim();
+  if (!targetId) return state;
+  const next = structuredClone(state || {});
+  const workspace = (Array.isArray(next.workspaces) ? next.workspaces : []).find((item) => item.id === targetId);
+  if (!workspace) return state;
+  const input = plan?.input || plan || {};
+  const label = String(input.label || input.repository || 'Tiinex docs').trim() || 'Tiinex docs';
+  workspace.discoveryProgress = {
+    sourceId: String(input.sourceId || input.id || '').trim(),
+    phase: 'default-workspace-bootstrap',
+    label: `Opening ${label} workspace`,
+    percent: null,
+    quantified: false,
+    active: true
+  };
+  workspace.workspaceBootstrap = Object.assign({}, workspace.workspaceBootstrap || {}, {
+    schema: 'tiinex.workspace.bootstrap.v1',
+    startState: input.bootstrapStartState || 'default-workspace-config',
+    boundary: input.bootstrapBoundary || 'explicit-default-config-path',
+    repository: input.repository || input.repo || '',
+    rootPath: input.rootPath || '',
+    workspaceMatch: input.workspaceMatch || '',
+    usefulStartPath: 'explicit-source-materialization-queued',
+    userFacingMessage: 'Opening Tiinex docs workspace.'
+  });
+  next.activeWorkspaceId = workspace.id;
+  return next;
+}

package/src/app/defaultWorkspaceStartCommand.js

@@ -0,0 +1,55 @@
+import { DEFAULT_WORKSPACE_START_ID, defaultWorkspaceStartPlan, stateWithDefaultWorkspaceStartProgress } from './defaultWorkspaceStart.js';
+import { openWorkspaceEntrypointSet } from '../workspaces/workspace.entrypointLifecycle.js';
+
+export function prepareDefaultWorkspaceStartCommand({ lifecycle, persistence, state = {}, workspaceConfig = {}, storage = null } = {}) {
+  const plan = defaultWorkspaceStartPlan(workspaceConfig);
+  if (!plan.ok) return { ok: false, error: 'default-workspace.config-unavailable', message: plan.message || 'Default workspace config is unavailable.', state, plan };
+  if (!lifecycle?.createWorkspace) return { ok: false, error: 'workspace.lifecycle-unavailable', message: 'Workspace lifecycle is unavailable.', state, plan };
+  const inputs = (plan.inputs || [plan.input]).filter(Boolean);
+  const opened = openWorkspaceEntrypointSet({
+    lifecycle,
+    state,
+    sourceInputs: inputs,
+    entry: { title: plan.workspaceName || 'Tiinex docs', markdown: workspaceConfig?.markdown || '', path: plan.input?.appConfigSourceUrl || 'embedded-default-workspace' },
+    workspaceInput(input, index) {
+      const id = index === 0 ? DEFAULT_WORKSPACE_START_ID : `${DEFAULT_WORKSPACE_START_ID}:${index + 1}:${workspaceIdSlug(input.label || input.repository || 'workspace')}`;
+      return {
+        id,
+        name: input.label || input.repository || plan.workspaceName || 'Tiinex docs',
+        boundary: 'embedded/default workspace config; startup owns source materialization'
+      };
+    },
+    afterCreate({ state: createdState, workspace, sourceInput }) {
+      let nextState = persistence?.hydrateWorkspaceWithLocalDeltas?.(createdState, workspace?.id, storage) || createdState;
+      nextState = stateWithDefaultWorkspaceStartProgress(nextState, workspace?.id, { input: sourceInput });
+      return nextState;
+    },
+    annotateWorkspace({ state: nextState, workspaceId, index }) {
+      const workspace = (nextState.workspaces || []).find((item) => item.id === workspaceId);
+      if (!workspace) return;
+      workspace.workspaceConfig = workspaceConfig && typeof workspaceConfig === 'object' ? JSON.parse(JSON.stringify(workspaceConfig)) : null;
+      workspace.workspaceBootstrap = Object.assign({}, workspace.workspaceBootstrap || {}, { workspaceSetSize: inputs.length, workspaceSetIndex: index });
+    },
+    registerSources: false
+  });
+  if (!opened?.ok) return { ok: false, error: opened?.error || 'default-workspace.create-failed', message: opened?.message || 'Could not create default workspace set.', state, plan };
+  return Object.assign({}, opened, {
+    plan,
+    sourceInput: opened.sourceInputs?.[0] || null,
+    notice: plan.message || 'Default workspace source registered.',
+    diagnostics: {
+      targetUrl: plan.input.appConfigSourceUrl || 'embedded-default-workspace',
+      ok: true,
+      selectedConvention: 'embedded-default-workspace',
+      selectedPlan: plan.selectedPlan || '',
+      input: plan.input,
+      inputs: plan.inputs || [plan.input],
+      diagnostics: { bootstrapStartState: plan.input.bootstrapStartState, boundary: plan.input.bootstrapBoundary },
+      message: plan.message || ''
+    }
+  });
+}
+
+function workspaceIdSlug(value = '') {
+  return String(value || 'workspace').toLowerCase().replace(/[^a-z0-9]+/gu, '-').replace(/^-|-$/gu, '').slice(0, 40) || 'workspace';
+}

package/src/app/durableLocalMutationPolicy.js

@@ -0,0 +1,21 @@
+import { isolatedDurableLocalAuthority } from './persistenceOwnership.js';
+
+export const DurableLocalMutationOperation = Object.freeze({
+  localMaterialIntake: 'local-material-intake',
+  localWorkspaceEntrypointIntake: 'local-workspace-entrypoint-intake',
+  localDraftCreate: 'local-draft-create',
+  localDraftDelete: 'local-draft-delete'
+});
+
+const GUARDED_OPERATIONS = new Set(Object.values(DurableLocalMutationOperation));
+
+export function durableLocalMutationDecision(ownership = null, operation = '') {
+  const normalizedOperation = String(operation || '');
+  if (!isolatedDurableLocalAuthority(ownership) || !GUARDED_OPERATIONS.has(normalizedOperation)) return Object.freeze({ ok: true, operation: normalizedOperation });
+  return Object.freeze({
+    ok: false,
+    error: 'local-durable-change.unavailable-in-isolated-shared-view',
+    operation: normalizedOperation,
+    notice: 'Local files and drafts cannot be added or changed while this shared view is isolated from your saved local recovery. Return to your local start before making browser-local changes.'
+  });
+}

package/src/app/githubMaterializationSummary.js

@@ -0,0 +1,69 @@
+export function summarizeGithubMaterialization(sourceLabel, out = {}) {
+  const okCount = Number(out.okCount || 0);
+  const failCount = Number(out.failCount || 0);
+  const warnings = Array.isArray(out.warnings) ? out.warnings : [];
+  const errors = Array.isArray(out.errors) ? out.errors : [];
+  const firstWarning = warnings[0];
+  const firstError = errors[0];
+  if (okCount > 0 && failCount === 0) {
+    return `Loaded ${okCount} source-backed record${okCount === 1 ? '' : 's'}${warnings.length ? `; ${warnings.length} warning${warnings.length === 1 ? '' : 's'}` : ''}${githubSurfaceSummary(out) ? ` · ${githubSurfaceSummary(out)}` : ''}.`;
+  }
+  if (okCount > 0) {
+    return `Loaded ${okCount} source-backed record${okCount === 1 ? '' : 's'}; ${failCount} failed/deferred${githubSurfaceSummary(out) ? ` · ${githubSurfaceSummary(out)}` : ''}.`;
+  }
+  if (firstWarning?.message) return `${sourceLabel} source registered. ${firstWarning.message}`;
+  if (firstError?.error) return `${sourceLabel} source registered; source loading failed: ${firstError.error}.`;
+  return `${sourceLabel} source registered; no source-backed records loaded.`;
+}
+
+export function githubSurfaceSummary(out = {}) {
+  const surfaces = out.diagnostics?.surfaces || {};
+  const parts = [];
+  const repo = surfaces.repoFiles || {};
+  const explicit = surfaces.explicitFiles || {};
+  const issues = surfaces.issueSnapshots || {};
+  if (repo.requested) parts.push(`Repo files: ${Number(repo.loaded || 0)} loaded${repo.discovered != null ? ` / ${Number(repo.discovered || 0)} discovered` : ''}`);
+  if (explicit.requested) parts.push(`Explicit files: ${Number(explicit.loaded || 0)} loaded${explicit.requestedCount != null ? ` / ${Number(explicit.requestedCount || 0)} requested` : ''}`);
+  if (issues.requested) {
+    const issueState = Number(issues.loaded || 0) > 0
+      ? `${Number(issues.loaded || 0)} loaded`
+      : issues.deferred || issues.unavailable
+        ? 'deferred in browser runtime'
+        : `${Number(issues.targets || 0)} targets`;
+    parts.push(`Issue snapshots: ${issueState}`);
+  }
+  return parts.join(' · ');
+}
+
+export function summarizeGithubAdapterResult(out = {}, options = {}) {
+  const warnings = Array.isArray(out.warnings) ? out.warnings : [];
+  const errors = Array.isArray(out.errors) ? out.errors : [];
+  return {
+    schema: 'tiinex.workspace.import.result.v1',
+    ok: Number(out.okCount || 0) > 0 || warnings.length > 0,
+    message: `GitHub source materialization: ${Number(out.okCount || 0)} loaded · ${warnings.length} warning${warnings.length === 1 ? '' : 's'} · ${errors.length} error${errors.length === 1 ? '' : 's'}${githubSurfaceSummary(out) ? ` · ${githubSurfaceSummary(out)}` : ''}.`,
+    counts: {
+      records: Number(out.okCount || 0),
+      assets: 0,
+      workspaceEntries: 0,
+      warnings: warnings.length,
+      errors: errors.length,
+      previewOmitted: 0
+    },
+    warnings,
+    errors,
+    diagnostics: Object.assign({ adapterId: 'github' }, out.diagnostics || {}, options.materialLedgerReceipt ? { materialLedgerReceipt: options.materialLedgerReceipt } : {})
+  };
+}
+
+export function normalizeRepository(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  try {
+    const url = new URL(raw);
+    const parts = url.pathname.replace(/^\/+|\.git$/g, '').split('/').filter(Boolean);
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : raw;
+  } catch {
+    return raw.replace(/^github\.com\//i, '').replace(/^https?:\/\/github\.com\//i, '').replace(/\.git$/i, '').replace(/^\/+|\/+$/g, '');
+  }
+}

package/src/app/githubProgress.js

@@ -0,0 +1,25 @@
+export function shouldCommitGithubProgress(progress = {}, state = {}) {
+  const now = Date.now();
+  const phase = String(progress.phase || 'source-materialization');
+  const label = String(progress.label || '');
+  const percent = Number(progress.percent ?? -1);
+  const percentDelta = Math.abs(percent - Number(state.percent ?? -1));
+  const terminal = progress.active === false || percent >= 100;
+  const changedPhase = phase !== state.phase;
+  const changedEnough = percent >= 0 && percentDelta >= 5;
+  const waited = now - Number(state.at || 0) >= 350;
+  if (!terminal && !changedPhase && !changedEnough && !waited) return false;
+  state.at = now;
+  state.phase = phase;
+  state.percent = percent;
+  state.label = label;
+  return true;
+}
+
+export function yieldForVisibleSourceProgress() {
+  return new Promise((resolve) => {
+    if (typeof window === 'undefined') return resolve();
+    const raf = window.requestAnimationFrame || ((fn) => window.setTimeout(fn, 16));
+    raf(() => window.setTimeout(resolve, 0));
+  });
+}

package/src/app/githubSourceInput.js

@@ -0,0 +1,47 @@
+export function existingGithubSourceForInput(input = {}, sources = []) {
+  const sourceId = String(input.sourceId || '').trim();
+  if (!sourceId || !Array.isArray(sources)) return null;
+  return sources.find((item) => String(item?.id || '') === sourceId) || null;
+}
+
+export function githubRequestedSurfaces(input = {}, fileRefs = []) {
+  return {
+    repoFiles: { requested: Boolean(input.repoDiscovery) },
+    explicitFiles: { requested: Boolean(fileRefs.length), requestedCount: fileRefs.length },
+    issueSnapshots: { requested: Boolean(input.issueDiscovery || input.issueUrls) }
+  };
+}
+
+export function githubSourceFormState(input = {}, sources = [], normalizeRepository) {
+  const repository = normalizeRepository(input.repository || input.repo || '');
+  const existingSource = existingGithubSourceForInput(input, sources);
+  return {
+    repository,
+    existingSource,
+    sourceId: existingSource?.id || input.sourceId || undefined,
+    rootPath: String(input.rootPath || input.root || existingSource?.rootPath || existingSource?.config?.rootPath || '.topics').trim() || '.topics',
+    ref: String(input.ref || existingSource?.ref || existingSource?.config?.ref || '').trim(),
+    label: input.label || existingSource?.label || repository
+  };
+}
+
+
+export function mergeGithubSurfaceStates(previous = {}, next = {}, selectedKeys = []) {
+  const keys = Array.isArray(selectedKeys) ? selectedKeys.filter(Boolean) : [];
+  if (!keys.length) return Object.assign({}, next || {});
+  const merged = JSON.parse(JSON.stringify(previous || {}));
+  for (const key of keys) merged[key] = Object.assign({}, next?.[key] || {}, { transportRefreshTier: next?.[key]?.transportTier || next?.[key]?.transportRefreshTier || '' });
+  for (const [key, value] of Object.entries(next || {})) {
+    if (keys.includes(key)) continue;
+    if (!merged[key] && value?.requested) merged[key] = Object.assign({}, value);
+  }
+  return merged;
+}
+
+export function mergeGithubRequestedSurfaces(previous = {}, next = {}, selectedKeys = []) {
+  const keys = Array.isArray(selectedKeys) ? selectedKeys.filter(Boolean) : [];
+  if (!keys.length) return Object.assign({}, next || {});
+  const merged = JSON.parse(JSON.stringify(previous || {}));
+  for (const key of keys) merged[key] = Object.assign({}, next?.[key] || {}, { requested: true });
+  return merged;
+}

package/src/app/githubSourceMaterializationCommand.js

@@ -0,0 +1,97 @@
+import { summarizeGithubAdapterResult } from './githubMaterializationSummary.js';
+import { mergeGithubSurfaceStates } from './githubSourceInput.js';
+import { appendImportSummary } from '../workspaces/workspace.import.js';
+import { materialLedgerSourceReceipt } from '../workspaces/workspace.materialLedger.js';
+import { assertCanonicalWorkspaceRuntimeState } from '../workspaces/workspace.runtimeCanonical.js';
+
+export function githubMaterializationDiscoveryState(out = {}) {
+  const okCount = Number(out.okCount || 0);
+  const failCount = Number(out.failCount || 0);
+  const errors = Array.isArray(out.errors) ? out.errors : [];
+  if (okCount > 0) return failCount > 0 ? 'partial' : 'loaded';
+  return failCount > 0 || errors.length ? 'failed' : 'unavailable';
+}
+
+export function applyGithubSourceMaterializationCommand(input = {}) {
+  const lifecycle = input.lifecycle;
+  if (!lifecycle) return { ok: false, error: 'lifecycle.missing', state: input.state };
+  const source = input.source || {};
+  const sourceId = String(input.sourceId || source.id || '').trim();
+  const workspaceId = String(input.workspaceId || '').trim();
+  if (!sourceId) return { ok: false, error: 'source.id.required', state: input.state };
+  let nextState = input.state;
+  const out = input.adapterResult || {};
+  const records = Array.isArray(out.records) ? out.records : [];
+  let insertResult = null;
+  if (Number(out.okCount || 0) > 0 || records.length) {
+    insertResult = lifecycle.addWorkspaceSourceRecords?.(nextState, workspaceId, sourceId, records, { preserveView: Boolean(input.preserveView) });
+    if (insertResult?.ok) nextState = insertResult.state;
+  }
+
+  const sourceWorkspace = workspaceFor(nextState, workspaceId, lifecycle);
+  const sourceRecordCount = countSourceRecords(sourceWorkspace, sourceId);
+  const discoveryState = githubMaterializationDiscoveryState(out);
+  const diagnostics = out.diagnostics || {};
+  const resolvedRef = String(diagnostics.resolvedRef || '').trim();
+  const updated = lifecycle.addWorkspaceSource?.(nextState, workspaceId, Object.assign({}, source, {
+    id: sourceId,
+    label: input.sourceLabel || source.label || source.repo || source.repository || 'Source',
+    repository: input.repository || source.repo || source.repository || '',
+    repo: input.repository || source.repo || source.repository || '',
+    ref: input.ref || resolvedRef || source.ref || '',
+    requestedRef: Object.prototype.hasOwnProperty.call(input, 'requestedRef') ? String(input.requestedRef || '').trim() : String(source.requestedRef ?? source.ref ?? '').trim(),
+    materializedCommit: exactCommit(input.materializedCommit || diagnostics.materializedCommit || source.materializedCommit),
+    rootPath: input.rootPath || source.rootPath || '.topics',
+    count: Number(sourceRecordCount || out.okCount || records.length || 0),
+    discoveryState,
+    repoDiscovery: Boolean(input.repoDiscovery ?? source.repoDiscovery),
+    issueDiscovery: Boolean(input.issueDiscovery ?? source.issueDiscovery),
+    issueUrls: input.issueUrls || source.issueUrls || source.config?.issueUrls || '',
+    explicitFileRefs: input.explicitFileRefs ?? source.explicitFileRefs ?? source.config?.explicitFileRefs ?? [],
+    workspaceMatch: input.workspaceMatch || source.workspaceMatch || '',
+    appConfigPlan: input.appConfigPlan || source.appConfigPlan || '',
+    openBehavior: input.openBehavior || source.openBehavior || '',
+    preferredDisplay: input.preferredDisplay || source.preferredDisplay || '',
+    requestedSurfaces: input.requestedSurfaces || source.requestedSurfaces || {},
+    surfaces: mergeGithubSurfaceStates(input.existingSource?.surfaces || source.surfaces || {}, diagnostics.surfaces || {}, input.selectedTransportSurfaces || []),
+    sourcePlan: diagnostics.sourcePlan || {},
+    recordAttribution: diagnostics.recordAttribution || [],
+    transportTiers: diagnostics.transportTiers || {},
+    transportOutcome: diagnostics.transportOutcome || {},
+    transportPlan: diagnostics.transportPlan || {},
+    governanceBoundary: diagnostics.governanceBoundary || source.governanceBoundary || {},
+    transportLabel: diagnostics.transportPlan?.label || input.transportLabel || source.transportLabel || '',
+    transportRefreshTier: input.transportRefreshTier || source.transportRefreshTier || ''
+  }), { sourceIdentityPolicy: 'refine-existing' });
+  if (updated?.ok) nextState = updated.state;
+
+  const finalWorkspace = workspaceFor(nextState, workspaceId, lifecycle);
+  const materialLedgerReceipt = finalWorkspace ? materialLedgerSourceReceipt(finalWorkspace, sourceId, { rawAdapterRecords: Number(out.okCount || records.length || 0) }, { displayOptions: finalWorkspace.displayOptions || {} }) : null;
+  const summary = summarizeGithubAdapterResult(out, { materialLedgerReceipt });
+  nextState = appendImportSummary(lifecycle, nextState, summary, {});
+  const canonicality = assertCanonicalWorkspaceRuntimeState(nextState, 'github-source-materialization');
+  if (!canonicality.ok) return { ok: false, error: 'workspace.runtime-candidate-model-leak', state: input.state, sourceId, source: updated?.source || source, canonicality };
+  return {
+    ok: true,
+    state: nextState,
+    sourceId,
+    source: updated?.source || source,
+    sourceRecordCount: countSourceRecords(workspaceFor(nextState, workspaceId, lifecycle), sourceId),
+    discoveryState,
+    insertResult,
+    materialLedgerReceipt,
+    summary
+  };
+}
+
+function exactCommit(value = '') { const commit = String(value || '').trim(); return /^[0-9a-f]{40}$/i.test(commit) ? commit : ''; }
+
+function workspaceFor(state = {}, workspaceId = '', lifecycle = {}) {
+  const targetId = String(workspaceId || state?.activeWorkspaceId || '').trim();
+  return (Array.isArray(state?.workspaces) ? state.workspaces : []).find((workspace) => workspace.id === targetId) || lifecycle.activeWorkspace?.(state) || null;
+}
+
+function countSourceRecords(workspace = {}, sourceId = '') {
+  const id = String(sourceId || '').trim();
+  return Array.isArray(workspace?.records) ? workspace.records.filter((record) => String(record?.source?.id || '') === id).length : 0;
+}