@tiinex/app 0.1.1

package/src/conformance/conformance.run.js

@@ -0,0 +1,238 @@
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { resolveLineage } from '@tiinex/core/lineage/lineage.resolve.js';
+import { traverseLoadedLineage } from '@tiinex/core/lineage/lineage.traverse.js';
+import { buildWorkspaceAuditView } from '../workspaces/workspace.auditView.js';
+import { buildLoadedAuditTraversalScope } from '../audit/audit.traverse.js';
+import { buildWorkspaceLineageView } from '../workspaces/workspace.lineageView.js';
+import { buildWorkspacePathTree } from '../workspaces/workspace.pathTree.js';
+import { summarizeWorkspaceMaterial } from '../workspaces/workspace.summary.js';
+import { createContinuationDraft, createReferenceDraft } from '@tiinex/core/transitions/record.transitions.js';
+import { buildPublicationPreflight } from '@tiinex/core/publication/publication.preflight.js';
+import { buildReingestPlan } from '@tiinex/core/reingest/reingest.plan.js';
+import { buildExportPackagePreflight } from '@tiinex/core/export/package.preflight.js';
+import { buildExportPackageContract, buildExportPackageManifest, buildExportPackageReceipt } from '@tiinex/core/export/package.manifest.js';
+import { buildExportPackageBundle, inspectExportPackageBundle } from '@tiinex/core/export/package.builder.js';
+import { buildExportPackageApplyResult, buildExportPackageImportPlan } from '@tiinex/core/export/package.apply.js';
+import { buildSourceBoundaryReport } from '@tiinex/core/diagnostics/sourceBoundary.report.js';
+import { buildSourceTransportReport } from '../diagnostics/sourceTransport.report.js';
+import { buildSchemaCapabilityRegistry, resolveSchemaCapabilities } from '@tiinex/core/schemas/capability.registry.js';
+import { listSurfaceFindings, surfaceRegistry } from '../surfaces/registry.js';
+import { buildArtifactCreationContract, listCreatableArtifactSchemas, validateArtifactCreationContract, validateArtifactCreationResult } from '@tiinex/core/schemas/creation.contracts.js';
+import { summarizeStoragePolicy } from '../storage/storage.policy.js';
+import { authorizeSourceTransport, summarizeSourceTransportOutcomes } from '../sources/transport.policy.js';
+import { conformanceFixtures } from './conformance.fixtures.js';
+
+export const CONFORMANCE_RESULT_SCHEMA_ID = 'tiinex.conformance.result.v1';
+
+export function materializeConformanceWorkspace(fixtureSet = conformanceFixtures) {
+  const workspace = {
+    id: fixtureSet.id || 'core-loaded-workspace-v1',
+    title: 'Conformance Fixture Workspace',
+    name: 'Conformance Fixture Workspace',
+    kind: 'workspace',
+    source: makeLocalSource(),
+    sources: [makeLocalSource()],
+    sourceOrder: ['local'],
+    records: (fixtureSet.records || []).map(materializeRecord),
+    assets: (fixtureSet.assets || []).map((asset) => Object.assign({}, asset)),
+    workspaceMergeCandidates: (fixtureSet.workspaceCandidates || []).map((candidate) => Object.assign({}, candidate)),
+    importResults: [{
+      schema: 'tiinex.workspace.import.result.v1',
+      ok: true,
+      message: 'Conformance fixture materialized.',
+      counts: {
+        records: (fixtureSet.records || []).length,
+        assets: (fixtureSet.assets || []).length,
+        workspaceEntries: (fixtureSet.workspaceCandidates || []).length,
+        warnings: 0,
+        errors: 0,
+        previewOmitted: 0
+      },
+      warnings: [],
+      errors: [],
+      diagnostics: { fixtureSet: fixtureSet.id || 'core-loaded-workspace-v1' },
+      at: '2026-07-21T00:00:00.000Z'
+    }],
+    importLog: [{ kind: 'conformance-fixture', at: '2026-07-21T00:00:00.000Z' }]
+  };
+  return workspace;
+}
+
+export function runConformanceFixtureSet(fixtureSet = conformanceFixtures) {
+  const workspace = materializeConformanceWorkspace(fixtureSet);
+  const lineage = resolveLineage(workspace.records, { depth: 'loaded-workspace-conformance' });
+  const lineageTraversal = traverseLoadedLineage(workspace.records, { startId: 'topic-child-trace', direction: 'ancestors', maxDepth: 4, resolvedLineage: lineage });
+  const lineageView = buildWorkspaceLineageView(workspace, { records: workspace.records });
+  const auditTraversalScope = buildLoadedAuditTraversalScope(workspace.records, { startId: 'topic-child-trace', direction: 'ancestors', maxDepth: 4, traversal: lineageTraversal });
+  const auditView = buildWorkspaceAuditView(workspace, { records: workspace.records });
+  const pathTree = buildWorkspacePathTree({
+    records: workspace.records,
+    assets: workspace.assets,
+    workspaceCandidates: workspace.workspaceMergeCandidates,
+    rootLabel: workspace.title
+  });
+  const summary = summarizeWorkspaceMaterial(workspace);
+  const sourceBoundary = buildSourceBoundaryReport(workspace);
+  const sourceTransport = buildSourceTransportReport(workspace);
+  const sourceTransportAuthorization = authorizeSourceTransport({ kind: 'conformance-no-fetch', sourceId: 'local', adapterId: 'local', requestedRequests: 0 }, { maxRequestsPerOperation: 1, now: '2026-07-21T02:00:00.000Z' });
+  const sourceTransportPolicySummary = summarizeSourceTransportOutcomes([sourceTransportAuthorization]);
+  const storagePolicy = summarizeStoragePolicy(workspace);
+  const schemaCapabilities = buildSchemaCapabilityRegistry();
+  const unknownSchemaCapabilityResolution = resolveSchemaCapabilities({ schemaId: 'tiinex.future.unknown.v9' });
+  const creatableArtifactSchemas = listCreatableArtifactSchemas();
+  const topicCreationContract = buildArtifactCreationContract({ schemaId: 'tiinex.topic.v1', transitionType: 'continue-from-record' });
+  const unknownCreationContract = buildArtifactCreationContract({ schemaId: 'tiinex.future.unknown.v9', transitionType: 'create-artifact' });
+  const publicationPreflight = buildPublicationPreflight(workspace);
+  const reingestPlan = buildReingestPlan(workspace, { sourceBoundary, publicationPreflight });
+  const exportPackagePreflight = buildExportPackagePreflight(workspace, { sourceBoundary, schemaCapabilities, unknownSchemaCapabilityResolution, publicationPreflight, reingestPlan });
+  const exportPackageManifest = buildExportPackageManifest(workspace, { sourceBoundary, schemaCapabilities, unknownSchemaCapabilityResolution, publicationPreflight, reingestPlan, preflight: exportPackagePreflight, clock: () => '2026-07-21T02:00:00.000Z' });
+  const exportPackageReceipt = buildExportPackageReceipt(exportPackageManifest, { clock: () => '2026-07-21T02:01:00.000Z' });
+  const exportPackageContract = buildExportPackageContract(workspace, { sourceBoundary, schemaCapabilities, unknownSchemaCapabilityResolution, publicationPreflight, reingestPlan, preflight: exportPackagePreflight, manifest: exportPackageManifest, receipt: exportPackageReceipt, clock: () => '2026-07-21T02:02:00.000Z' });
+  const exportPackageBundle = buildExportPackageBundle(workspace, { contract: exportPackageContract, clock: () => '2026-07-21T02:03:00.000Z' });
+  const exportPackageBundleInspection = inspectExportPackageBundle(exportPackageBundle);
+  const exportPackageImportPlan = buildExportPackageImportPlan(exportPackageBundle, { inspection: exportPackageBundleInspection });
+  const exportPackageApplyResult = buildExportPackageApplyResult(exportPackageBundle, { importPlan: exportPackageImportPlan });
+  const transitionParent = workspace.records.find((record) => record.id === 'topic-child-trace') || workspace.records[0];
+  const continuationDraft = transitionParent ? createContinuationDraft(transitionParent, { id: 'tiinex.topic.v1', label: 'Topic' }, { title: 'Continue Fixture', summary: 'Continuation fixture draft.' }, { clock: () => '2026-07-21T01:00:00.000Z' }) : null;
+  const referenceDraft = transitionParent ? createReferenceDraft(transitionParent, { title: 'Reference Fixture', summary: 'Reference fixture draft.' }, { clock: () => '2026-07-21T01:00:00.000Z' }) : null;
+  const topicCreationContractValidation = validateArtifactCreationContract(topicCreationContract);
+  const unknownCreationContractValidation = validateArtifactCreationContract(unknownCreationContract);
+  const continuationCreationValidation = continuationDraft && transitionParent ? validateArtifactCreationResult(continuationDraft, transitionParent, { contract: topicCreationContract }) : null;
+  return {
+    schema: CONFORMANCE_RESULT_SCHEMA_ID,
+    fixtureSet: fixtureSet.id || 'core-loaded-workspace-v1',
+    workspace,
+    lineage,
+    lineageView,
+    lineageTraversal,
+    auditView,
+    auditTraversalScope,
+    pathTree,
+    summary,
+    transitions: { continuationDraft, referenceDraft },
+    sourceBoundary,
+    sourceTransport,
+    sourceTransportAuthorization,
+    sourceTransportPolicySummary,
+    storagePolicy,
+    schemaCapabilities,
+    surfaceRegistry,
+    surfaceFindings: listSurfaceFindings(),
+    unknownSchemaCapabilityResolution,
+    creationContracts: { creatableArtifactSchemas, topicCreationContract, unknownCreationContract, topicCreationContractValidation, unknownCreationContractValidation, continuationCreationValidation },
+    publicationPreflight,
+    reingestPlan,
+    exportPackagePreflight,
+    exportPackageManifest,
+    exportPackageReceipt,
+    exportPackageContract,
+    exportPackageBundle,
+    exportPackageBundleInspection,
+    exportPackageImportPlan,
+    exportPackageApplyResult,
+    invariants: summarizeConformanceInvariants({ workspace, lineage, lineageTraversal, auditTraversalScope, auditView, continuationDraft, referenceDraft, sourceBoundary, sourceTransport, sourceTransportAuthorization, sourceTransportPolicySummary, storagePolicy, schemaCapabilities, unknownSchemaCapabilityResolution, creatableArtifactSchemas, topicCreationContract, unknownCreationContract, topicCreationContractValidation, unknownCreationContractValidation, continuationCreationValidation, publicationPreflight, reingestPlan, exportPackagePreflight, exportPackageManifest, exportPackageReceipt, exportPackageContract, exportPackageBundle, exportPackageBundleInspection, exportPackageImportPlan, exportPackageApplyResult })
+  };
+}
+
+export function summarizeConformanceInvariants(result = {}) {
+  const workspace = result.workspace || {};
+  const lineage = result.lineage || {};
+  const audit = result.auditView || {};
+  const records = Array.isArray(workspace.records) ? workspace.records : [];
+  const localBoundaryViolations = records.filter((record) => record.source?.adapterId && record.source.adapterId !== 'local');
+  const parentEdges = (lineage.edges || []).filter((edge) => edge.kind === 'parent' && edge.status !== 'missing');
+  const missingParentFindings = (lineage.findings || []).filter((finding) => finding.code === 'lineage.parent.missing');
+  const fallbackItems = (audit.items || []).filter((item) => item.fallbackUsed);
+  const invalidItems = (audit.items || []).filter((item) => item.status === 'invalid-or-incomplete');
+  return {
+    schema: 'tiinex.conformance.invariants.v1',
+    localBoundaryClean: localBoundaryViolations.length === 0,
+    localBoundaryViolations: localBoundaryViolations.map((record) => record.id || record.path),
+    loadedParentEdges: parentEdges.length,
+    missingParentFindings: missingParentFindings.length,
+    lineageTraversalPresent: result.lineageTraversal?.schema === 'tiinex.lineage.traversal.v1',
+    lineageTraversalLoadedOnly: result.lineageTraversal?.boundary?.includes('no remote fetch') === true,
+    lineageTraversalVisitsAncestors: (result.lineageTraversal?.nodes || []).some((node) => node.id === 'topic-parent') && (result.lineageTraversal?.nodes || []).some((node) => node.id === 'topic-child-trace'),
+    auditTraversalScopePresent: result.auditTraversalScope?.schema === 'tiinex.audit.traversal.scope.v1',
+    auditTraversalScopeLoadedOnly: result.auditTraversalScope?.boundary?.includes('no remote fetch') === true,
+    auditTraversalScopeAuditsVisited: (result.auditTraversalScope?.counts?.auditedNodes || 0) === (result.auditTraversalScope?.counts?.visitedNodes || -1),
+    rootFallbackItems: fallbackItems.length,
+    invalidItems: invalidItems.length,
+    continuationEnvelope: Boolean(result.continuationDraft?.markdown?.includes('Envelope Schema') && result.continuationDraft?.markdown?.includes('Continuity Integrity')),
+    referenceEnvelope: Boolean(result.referenceDraft?.markdown?.includes('Envelope Schema') && result.referenceDraft?.markdown?.includes('Continuity Integrity')),
+    continuationValidationClean: result.continuationDraft?.validation?.ok === true,
+    referenceValidationClean: result.referenceDraft?.validation?.ok === true,
+    transitionSourceBoundaryClean: [result.continuationDraft, result.referenceDraft].every((draft) => draft && String(draft.sourceMode || '').startsWith('local') && !draft.source?.adapterId),
+    sourceBoundaryClean: result.sourceBoundary?.status === 'clean',
+    sourceTransportPresent: result.sourceTransport?.schema === 'tiinex.sourceTransport.report.v1',
+    sourceTransportObservationOnly: result.sourceTransport?.boundary?.includes('must not infer provenance') === true,
+    sourceTransportCleanForLocalFixture: result.sourceTransport?.status === 'clean',
+    sourceTransportPolicyPresent: result.sourceTransportAuthorization?.schema === 'tiinex.sourceTransport.authorization.v1',
+    sourceTransportPolicyDoesNotFetchLocalFixture: result.sourceTransportAuthorization?.allowed === true && result.sourceTransportAuthorization?.operation?.requestedRequests === 0,
+    sourceTransportPolicySummaryClean: result.sourceTransportPolicySummary?.status === 'clean',
+    storagePolicyPresent: result.storagePolicy?.schema === 'tiinex.storage.policy.v1',
+    storagePolicyCountsMaterial: (result.storagePolicy?.counts?.records || 0) >= 1 && (result.storagePolicy?.counts?.assets || 0) >= 1,
+    schemaCapabilityRegistryPresent: Boolean(result.schemaCapabilities?.schema),
+    schemaCapabilityRegistryClean: result.schemaCapabilities?.status === 'clean',
+    schemaCapabilityRegistryCoversModules: (result.schemaCapabilities?.counts?.modules || 0) >= 7,
+    schemaCapabilityUnknownUsesRootFallback: result.unknownSchemaCapabilityResolution?.fallbackUsed === true && result.unknownSchemaCapabilityResolution?.descriptor?.moduleId === 'tiinex.root.v1',
+    surfaceRegistryPresent: result.surfaceRegistry?.schema === 'tiinex.surface.registry.v1',
+    surfaceRegistryNoParityClaims: (result.surfaceRegistry?.counts?.parity || 0) === 0,
+    surfaceRegistryHasPartialCoreViews: (result.surfaceRegistry?.counts?.partial || 0) >= 4,
+    surfaceRegistryScaffoldsAreDisclosed: ((result.surfaceRegistry?.counts?.scaffold || 0) + (result.surfaceRegistry?.counts?.unavailable || 0)) === 0 || (result.surfaceFindings || []).some((finding) => finding.code === 'surface.status.scaffold'),
+    artifactCreationContractsPresent: Array.isArray(result.creatableArtifactSchemas) && result.creatableArtifactSchemas.length >= 2,
+    artifactCreationContractReady: result.topicCreationContract?.status === 'ready' && result.topicCreationContractValidation?.ok === true,
+    artifactCreationUnknownBlocked: result.unknownCreationContract?.status === 'blocked' && result.unknownCreationContractValidation?.ok === false,
+    artifactCreationResultValidates: result.continuationCreationValidation?.ok === true,
+    artifactCreationResultLocalOnly: result.continuationDraft?.creationContract?.resultBoundary?.remoteWrite === false && !result.continuationDraft?.source?.adapterId,
+    publicationPreflightPresent: Boolean(result.publicationPreflight?.schema),
+    publicationPreflightProtectsNonDrafts: (result.publicationPreflight?.counts?.blockedLocalDrafts || 0) >= 1,
+    reingestPlanPresent: Boolean(result.reingestPlan?.schema),
+    reingestPlanProtectsLocalMaterial: (result.reingestPlan?.counts?.blockedLocalTargets || 0) >= 1,
+    exportPackagePreflightPresent: Boolean(result.exportPackagePreflight?.schema),
+    exportPackageProtectsLocalMaterial: (result.exportPackagePreflight?.counts?.blockedLocalEntries || 0) >= 1,
+    exportPackageKeepsAssetsAsAssets: (result.exportPackagePreflight?.assetEntries || []).every((entry) => entry.kind === 'asset'),
+    exportPackageManifestPresent: Boolean(result.exportPackageManifest?.schema),
+    exportPackageManifestMatchesPreflight: (result.exportPackageManifest?.counts?.sourceReferences || 0) === (result.exportPackagePreflight?.counts?.sourceReferenceEntries || 0),
+    exportPackageManifestKeepsAssetsAsAssets: (result.exportPackageManifest?.material?.assets || []).every((entry) => entry.kind === 'asset'),
+    exportPackageReceiptPresent: Boolean(result.exportPackageReceipt?.schema),
+    exportPackageContractPresent: Boolean(result.exportPackageContract?.schema),
+    exportPackageContractNoMutation: result.exportPackageContract?.boundary?.includes('No-mutation') === true,
+    exportPackageBundlePresent: Boolean(result.exportPackageBundle?.schema),
+    exportPackageBundleNoMutation: result.exportPackageBundle?.boundary?.includes('mutates no source') === true,
+    exportPackageBundleHasControlFiles: ['tiinex.package/index.json', 'tiinex.package/manifest.json', 'tiinex.package/receipt.json'].every((path) => (result.exportPackageBundle?.files || []).some((file) => file.path === path)),
+    exportPackageBundleInspectionValid: result.exportPackageBundleInspection?.status === 'valid',
+    exportPackageBundleKeepsAssetsOutOfArtifacts: (result.exportPackageBundle?.files || []).filter((file) => String(file.kind || '').startsWith('asset')).every((file) => !String(file.path || '').startsWith('artifacts/')),
+    exportPackageBundleKeepsSourceRefsOutOfArtifacts: (result.exportPackageBundle?.files || []).filter((file) => file.kind === 'source-reference').every((file) => !String(file.path || '').startsWith('artifacts/')),
+    exportPackageImportPlanPresent: Boolean(result.exportPackageImportPlan?.schema),
+    exportPackageImportPlanNoGithubGuess: (result.exportPackageImportPlan?.records || []).every((record) => record.source?.adapterId !== 'github'),
+    exportPackageImportPlanKeepsSourceRefsSeparate: (result.exportPackageImportPlan?.sourceReferences || []).length === (result.exportPackageManifest?.counts?.sourceReferences || 0),
+    exportPackageImportPlanKeepsAssetsAsAssets: (result.exportPackageImportPlan?.assets || []).every((asset) => asset.schema === 'tiinex.local.asset.v1'),
+    exportPackageApplyResultPresent: Boolean(result.exportPackageApplyResult?.schema),
+    exportPackageApplyResultNoRemoteMutation: result.exportPackageApplyResult?.adapterResult?.diagnostics?.noRemoteFetch === true && result.exportPackageApplyResult?.adapterResult?.diagnostics?.noSourceMutation === true,
+    exportPackageApplyKeepsSourceRefsOutOfRecords: (result.exportPackageApplyResult?.adapterResult?.records || []).every((record) => record.source?.adapterId !== 'github')
+  };
+}
+
+function materializeRecord(fixture = {}) {
+  const record = createRecordFromMarkdown(fixture.markdown || '', { path: fixture.path, name: fixture.title, sourceMode: fixture.sourceMode || 'local-fixture' });
+  return Object.assign({}, record, {
+    id: fixture.id || `record:${fixture.path || fixture.title}`,
+    path: fixture.path || record.path || '',
+    title: fixture.title || record.title,
+    sourceMode: fixture.sourceMode || 'local-fixture',
+    source: makeLocalSource({ path: fixture.path || record.path || '' })
+  });
+}
+
+function makeLocalSource(extra = {}) {
+  return Object.assign({
+    id: 'local',
+    label: 'Local session',
+    adapterId: 'local',
+    kind: 'local-session',
+    sourceKind: 'local.session',
+    boundary: 'Browser-local session material; no GitHub provenance inferred.',
+    count: 0
+  }, extra);
+}

package/src/data/applicationDataStore.js

@@ -0,0 +1,23 @@
+export function createApplicationDataStore(initialSnapshot = null) {
+  let snapshot = deepFreeze(initialSnapshot ?? emptySnapshot());
+  const listeners = new Set();
+  return Object.freeze({
+    getSnapshot: () => snapshot,
+    getServerSnapshot: () => snapshot,
+    subscribe(listener) {
+      if (typeof listener !== 'function') throw new TypeError('listener must be a function');
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    replace(nextSnapshot) {
+      if (!nextSnapshot || typeof nextSnapshot !== 'object') throw new TypeError('application data snapshot must be an object');
+      const next = deepFreeze(nextSnapshot);
+      if (next === snapshot) return snapshot;
+      snapshot = next;
+      for (const listener of [...listeners]) { try { listener(); } catch { /* A faulty observer cannot starve other read-only observers. */ } }
+      return snapshot;
+    }
+  });
+}
+function emptySnapshot() { return { schema: 'tiinex.core.application-data.v1', workspaces: [], records: [], relations: [], findings: [], boundary: 'empty application data' }; }
+function deepFreeze(value) { if (Array.isArray(value)) return Object.freeze(value.map(deepFreeze)); if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, deepFreeze(item)]))); }

package/src/data/companionAccess.js

@@ -0,0 +1,35 @@
+export function createCompanionAccess(options = {}) {
+  const readers = new Map(Object.entries(options.resourceReaders || {}));
+  let assets = new Map();
+  return Object.freeze({
+    setWorkspaces(workspaces) {
+      assets = new Map(workspaces.flatMap(w => (w.assets || []).map(asset => [`workspace:${w.id}::${asset.path}`, asset])));
+    },
+    async read(resource, { signal } = {}) {
+      signal?.throwIfAborted();
+      if (!resource?.providerId) throw new TypeError('Resolved companion resource required.');
+      const reader = readers.get(resource.providerId);
+      let result;
+      if (reader) result = await reader(Object.freeze({ ...resource }), { signal, maxBytes: options.maxResourceBytes || 16 * 1024 * 1024 });
+      else if (resource.providerId.startsWith('workspace:')) {
+        const asset = assets.get(`${resource.providerId}::${resource.path}`);
+        if (!asset) throw new Error('Companion bytes are not available in this Workspace.');
+        if (asset.bytes instanceof Uint8Array) result = { bytes: new Uint8Array(asset.bytes), mediaType: asset.type || asset.mediaType };
+        else if (/^data:image\/png;base64,/i.test(asset.dataUrl || '')) {
+          const encoded = asset.dataUrl.slice(asset.dataUrl.indexOf(',') + 1);
+          result = { bytes: Uint8Array.from(atob(encoded), c => c.charCodeAt(0)), mediaType: 'image/png' };
+        } else throw new Error('Companion metadata is present, but its bytes must be loaded first.');
+      } else throw new Error('No resource reader registered for this companion provider.');
+      signal?.throwIfAborted();
+      if (!(result?.bytes instanceof Uint8Array)) throw new TypeError('Resource reader must return Uint8Array bytes.');
+      if (result.bytes.length > (options.maxResourceBytes || 16 * 1024 * 1024)) throw new Error('Companion exceeds the configured byte limit.');
+      const bytes = new Uint8Array(result.bytes);
+      if (resource.sha256) {
+        if (!/^[a-f0-9]{64}$/i.test(resource.sha256)) throw new Error('Invalid companion digest declaration.');
+        const digest = Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes)), n => n.toString(16).padStart(2,'0')).join('');
+        if (digest !== resource.sha256.toLowerCase()) throw new Error('Companion integrity mismatch.');
+      }
+      return Object.freeze({ bytes, mediaType: result.mediaType || resource.mediaType || 'application/octet-stream', integrity: resource.sha256 ? 'verified' : 'not-declared' });
+    }
+  });
+}

package/src/diagnostics/events.js

@@ -0,0 +1 @@
+export function diagnosticEvent(type, data = {}) { return { type, data, at: new Date().toISOString() }; }

package/src/diagnostics/invariant.js

@@ -0,0 +1 @@
+export function invariant(condition, message) { if (!condition) throw new Error(message); }

package/src/diagnostics/schemaBindingChecks.js

@@ -0,0 +1 @@
+export function checkSchemaBinding(binding) { return Boolean(binding?.schemaId && binding?.checksum); }

package/src/diagnostics/schemaModuleChecks.js

@@ -0,0 +1 @@
+export function checkSchemaModule(module) { return Boolean(module?.id && module?.binding); }

package/src/diagnostics/sourceBoundaryChecks.js

@@ -0,0 +1,5 @@
+export function checkSourceBoundary(source) {
+  if (!source) return { ok: true, severity: 'info', code: 'source.draft.default' };
+  if (source.kind === 'github-source-backed' && !source.permalink) return { ok: false, severity: 'error', code: 'source.github.missing-permalink' };
+  return { ok: true, severity: 'info', code: 'source.boundary.visible' };
+}

package/src/diagnostics/sourceTransport.report.js

@@ -0,0 +1,190 @@
+export const SOURCE_TRANSPORT_REPORT_SCHEMA_ID = 'tiinex.sourceTransport.report.v1';
+
+export function buildSourceTransportReport(workspace = {}, input = {}) {
+  const sources = Array.isArray(input.sources) ? input.sources : (Array.isArray(workspace.sources) ? workspace.sources : []);
+  const importResults = Array.isArray(input.importResults) ? input.importResults : (Array.isArray(workspace.importResults) ? workspace.importResults : []);
+  const adapterResults = Array.isArray(input.adapterResults) ? input.adapterResults : [];
+  const rawEvents = [
+    ...sources.flatMap((source) => sourceRegistrationEvents(source)),
+    ...importResults.flatMap((result, index) => eventsFromResult(result, { resultKind: 'workspace-import-result', resultIndex: index })),
+    ...adapterResults.flatMap((result, index) => eventsFromResult(result, { resultKind: 'adapter-result', resultIndex: index }))
+  ];
+  const events = dedupeEvents(rawEvents.map(normalizeTransportEvent).filter(Boolean));
+  const errors = events.filter((event) => event.severity === 'error').length;
+  const warnings = events.filter((event) => event.severity === 'warning').length;
+  const degraded = events.filter((event) => event.status === 'degraded').length;
+  const blocked = events.filter((event) => event.status === 'blocked').length;
+  const rateLimited = events.filter((event) => event.classification === 'rate-limited-or-forbidden').length;
+  const unavailable = events.filter((event) => event.classification === 'unavailable' || event.classification === 'network-error').length;
+  const notFound = events.filter((event) => event.classification === 'not-found').length;
+  const retryable = events.filter((event) => event.retryable === true).length;
+  const rawDiagnostics = importResults.concat(adapterResults).map((result) => result?.diagnostics || {});
+  const requestCount = rawDiagnostics.reduce((sum, diagnostics) => sum + numberField(diagnostics, ['requests', 'requestCount', 'fetchRequests', 'fileRefs', 'explicitFileRefs', 'discoveredFileRefs']), 0);
+  const cacheHits = rawDiagnostics.reduce((sum, diagnostics) => sum + numberField(diagnostics, ['cacheHits', 'cacheHitCount']), 0);
+  const cacheMisses = rawDiagnostics.reduce((sum, diagnostics) => sum + numberField(diagnostics, ['cacheMisses', 'cacheMissCount']), 0);
+
+  return Object.freeze({
+    schema: SOURCE_TRANSPORT_REPORT_SCHEMA_ID,
+    workspaceId: workspace.id || '',
+    status: errors || blocked ? 'blocked' : warnings || degraded || rateLimited || unavailable || notFound ? 'degraded' : 'clean',
+    boundary: 'Transport diagnostics are observation-only. They may classify source availability, rate limits, cache hints, and retryability, but must not infer provenance or trigger hidden fetches.',
+    counts: Object.freeze({
+      sources: sources.length,
+      importResults: importResults.length,
+      adapterResults: adapterResults.length,
+      events: events.length,
+      requests: requestCount,
+      cacheHits,
+      cacheMisses,
+      rateLimited,
+      unavailable,
+      notFound,
+      retryable,
+      errors,
+      warnings
+    }),
+    events: Object.freeze(events),
+    nextActions: Object.freeze(nextActionsFor(events))
+  });
+}
+
+export function normalizeTransportEvent(input = {}) {
+  if (!input) return null;
+  const code = String(input.code || input.error || input.type || input.message || 'transport.event').trim();
+  const message = String(input.message || input.error || code || 'Transport event').trim();
+  const statusCode = Number(input.status || input.httpStatus || parseStatus(message) || 0) || 0;
+  const classification = classifyTransportIssue(Object.assign({}, input, { code, message, status: statusCode || input.status }));
+  const severity = normalizeSeverity(input.severity, classification);
+  return Object.freeze({
+    schema: 'tiinex.sourceTransport.event.v1',
+    sourceId: input.sourceId || input.source?.id || '',
+    adapterId: input.adapterId || input.source?.adapterId || input.diagnostics?.adapterId || '',
+    resultKind: input.resultKind || '',
+    resultIndex: Number.isFinite(Number(input.resultIndex)) ? Number(input.resultIndex) : null,
+    severity,
+    status: severity === 'error' ? 'blocked' : classification === 'clean' ? 'clean' : 'degraded',
+    code,
+    message,
+    classification,
+    retryable: retryableFor(classification, statusCode),
+    statusCode,
+    url: input.url || input.diagnostics?.url || input.diagnostics?.treeUrl || '',
+    ref: input.ref || input.path || '',
+    cache: normalizeCache(input)
+  });
+}
+
+export function classifyTransportIssue(input = {}) {
+  const code = String(input.code || input.error || '').toLowerCase();
+  const message = String(input.message || input.error || '').toLowerCase();
+  const status = Number(input.status || input.statusCode || parseStatus(message) || 0) || 0;
+  if (!code && !message && !status) return 'clean';
+  if (status === 403 || code.includes('rate-limit') || code.includes('forbidden') || message.includes('rate limit') || message.includes('forbidden')) return 'rate-limited-or-forbidden';
+  if (status === 404 || code.includes('not-found') || message.includes('not found')) return 'not-found';
+  if (status === 401 || status === 422 || code.includes('permission') || code.includes('auth')) return 'permission-or-auth';
+  if (status >= 500 || code.includes('network') || code.includes('fetch') || message.includes('failed to fetch') || message.includes('network')) return 'network-error';
+  if (code.includes('unavailable') || message.includes('unavailable') || code.includes('deferred')) return 'unavailable';
+  if (code.includes('cache')) return 'cache';
+  if (code.includes('source.github.ref.unpinned') || code.includes('ref.unpinned')) return 'unpinned-source';
+  if (code.includes('blocked')) return 'blocked';
+  return status >= 400 ? 'transport-error' : 'degraded';
+}
+
+function eventsFromResult(result = {}, context = {}) {
+  const diagnostics = result?.diagnostics || {};
+  const events = [];
+  const base = {
+    sourceId: result.sourceId || diagnostics.sourceId || '',
+    adapterId: result.adapterId || diagnostics.adapterId || '',
+    resultKind: context.resultKind || '',
+    resultIndex: context.resultIndex,
+    diagnostics
+  };
+  for (const warning of Array.isArray(result.warnings) ? result.warnings : []) {
+    events.push(Object.assign({}, base, warning, { severity: warning.severity || 'warning' }));
+  }
+  for (const error of Array.isArray(result.errors) ? result.errors : []) {
+    events.push(Object.assign({}, base, error, { severity: error.severity || 'error' }));
+  }
+  if (Array.isArray(diagnostics.transportEvents)) {
+    for (const event of diagnostics.transportEvents) events.push(Object.assign({}, base, event));
+  }
+  if (diagnostics.discoveryUnavailable) {
+    events.push(Object.assign({}, base, {
+      severity: 'warning',
+      code: 'transport.discovery.unavailable',
+      message: diagnostics.discoveryError || 'Source discovery unavailable.',
+      url: diagnostics.treeUrl || ''
+    }));
+  }
+  return events;
+}
+
+function sourceRegistrationEvents(source = {}) {
+  const adapterId = String(source.adapterId || '').trim();
+  if (!adapterId || adapterId === 'local') return [];
+  if (adapterId === 'github') {
+    const events = [];
+    if (!String(source.ref || source.resolvedRef || source.config?.ref || '').trim()) {
+      events.push({ sourceId: source.id || '', adapterId, severity: 'warning', code: 'source.github.ref.unpinned', message: 'GitHub source has no pinned/resolved ref; source transport and re-ingest remain degraded.' });
+    }
+    return events;
+  }
+  return [{ sourceId: source.id || '', adapterId, severity: 'info', code: 'source.transport.explicit-adapter', message: `Source uses explicit ${adapterId} transport boundary.` }];
+}
+
+function normalizeSeverity(severity, classification) {
+  const raw = String(severity || '').toLowerCase();
+  if (raw === 'error' || raw === 'warning' || raw === 'info') return raw;
+  if (classification === 'blocked' || classification === 'permission-or-auth' || classification === 'transport-error') return 'error';
+  if (classification === 'clean') return 'info';
+  return 'warning';
+}
+
+function retryableFor(classification, statusCode) {
+  if (classification === 'rate-limited-or-forbidden') return true;
+  if (classification === 'network-error') return true;
+  if (statusCode >= 500) return true;
+  return false;
+}
+
+function normalizeCache(input = {}) {
+  const cacheState = input.cacheState || input.diagnostics?.cacheState || '';
+  const cacheHit = input.cacheHit === true || input.diagnostics?.cacheHit === true;
+  if (!cacheState && !cacheHit) return Object.freeze({ state: 'unknown', hit: false });
+  return Object.freeze({ state: cacheState || (cacheHit ? 'hit' : 'unknown'), hit: cacheHit });
+}
+
+function parseStatus(value = '') {
+  const match = String(value || '').match(/\b(40[134]|404|429|5\d\d)\b/);
+  return match ? Number(match[1]) : 0;
+}
+
+function numberField(diagnostics = {}, keys = []) {
+  for (const key of keys) {
+    const value = Number(diagnostics?.[key] || 0);
+    if (Number.isFinite(value) && value > 0) return value;
+  }
+  return 0;
+}
+
+function dedupeEvents(events = []) {
+  const seen = new Set();
+  const out = [];
+  for (const event of events) {
+    const key = [event.adapterId, event.sourceId, event.code, event.ref, event.url, event.statusCode].join('|');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(event);
+  }
+  return out;
+}
+
+function nextActionsFor(events = []) {
+  const actions = [];
+  if (events.some((event) => event.classification === 'rate-limited-or-forbidden')) actions.push('Retry later, reduce discovery scope, or use explicit file refs/raw URLs.');
+  if (events.some((event) => event.classification === 'not-found')) actions.push('Verify repo/ref/path or replace with an explicit reachable target.');
+  if (events.some((event) => event.classification === 'unpinned-source')) actions.push('Pin or resolve source refs before publish/re-ingest/export review.');
+  if (events.some((event) => event.classification === 'network-error')) actions.push('Keep loaded local/session material; retry network transport when available.');
+  return actions;
+}

package/src/discovery/discovery.controls.js

@@ -0,0 +1,7 @@
+export const discoveryControlContract = {
+  type: 'tiinex.web.discovery.controls.v1',
+  owner: 'src/discovery',
+  rule: 'Clarity comes from layout, placement, color, affordance, and consistent behavior before explanatory prose.',
+  controls: ['verse', 'reader', 'search', 'source-filter', 'audit-command'],
+  sourceTruth: 'controls may filter or arrange loaded material; they must not promote local/draft/static material into source-backed material'
+};