@tiinex/app 0.1.1

package/src/sources/source.model.case.mjs

@@ -0,0 +1,26 @@
+import assert from 'assert';
+import { isLocalSource, isSourceBacked, normalizeSourceRegistration, SourceKind } from './source.model.js';
+import { resolveSourceBoundary, mustNotGuessGithubSource } from './source.boundaries.js';
+import { resolveSource } from './source.resolve.js';
+
+const local = normalizeSourceRegistration({ id: 'local', kind: 'local', label: 'Local' });
+assert(local.adapterId === 'local', 'local source should infer local adapter');
+assert(local.sourceKind === SourceKind.localSession, 'local source should infer local session kind');
+assert(isLocalSource(local), 'local source predicate should be true');
+assert(!isSourceBacked(local), 'local source should not be source-backed');
+assert(mustNotGuessGithubSource(local), 'local source must never require github provenance');
+
+const github = normalizeSourceRegistration({ kind: 'github-tree', repo: 'Tiinex/docs', ref: 'master', rootPath: '.topics' });
+assert(github.adapterId === 'github', 'github-tree should infer github adapter');
+assert(github.sourceKind === SourceKind.githubRepo, 'github-tree should infer github repo source kind');
+assert(github.config.repo === 'Tiinex/docs', 'github config should preserve repo');
+assert(isSourceBacked(github), 'github source should be source-backed');
+
+const boundary = resolveSourceBoundary(github);
+assert(boundary.githubPolicy === 'explicit', 'github source with repo should be explicit');
+assert(boundary.adapterId === 'github', 'boundary should expose adapter id');
+
+const unsafe = resolveSource({ adapterId: 'github', sourceKind: 'github.repo' });
+assert(unsafe.githubPolicy === 'not-guessed', 'github source without repo/permalink must not be guessed');
+
+console.log('✓ source model tests passed');

package/src/sources/source.model.js

@@ -0,0 +1,56 @@
+export const SourceKind = Object.freeze({
+  github: 'github-source-backed',
+  githubRepo: 'github.repo',
+  githubFile: 'github.file',
+  local: 'local-file',
+  localSession: 'local.session',
+  draft: 'draft',
+  static: 'static-fixture',
+  gitNative: 'git.native-repo',
+  exportShare: 'export.share-package'
+});
+
+export const SourceAuthority = Object.freeze({ explicit: 'explicit', notGuessed: 'not-guessed', unavailable: 'unavailable' });
+
+export function normalizeSourceRegistration(source = {}) {
+  const adapterId = String(source.adapterId || inferAdapterId(source)).trim() || 'local';
+  const sourceKind = String(source.sourceKind || inferSourceKind(source)).trim();
+  return Object.freeze(Object.assign({}, source, {
+    adapterId,
+    sourceKind,
+    config: Object.freeze(Object.assign({}, source.config || legacyConfig(source)))
+  }));
+}
+
+export function isLocalSource(source = {}) {
+  return source.id === 'local' || source.adapterId === 'local' || source.kind === 'local';
+}
+
+export function isSourceBacked(source = {}) {
+  return !isLocalSource(source) && Boolean(source.adapterId || source.sourceKind || source.repo || source.permalink);
+}
+
+function inferAdapterId(source = {}) {
+  if (source.adapterId) return source.adapterId;
+  if (source.kind === 'github-tree' || source.kind === SourceKind.github || source.repo || source.permalink) return 'github';
+  if (source.kind === 'static' || source.kind === SourceKind.static) return 'static';
+  if (source.kind === 'git-native' || source.sourceKind === SourceKind.gitNative) return 'git-native';
+  return 'local';
+}
+
+function inferSourceKind(source = {}) {
+  if (source.sourceKind) return source.sourceKind;
+  if (source.kind === 'github-tree' || source.repo) return SourceKind.githubRepo;
+  if (source.kind === 'static') return SourceKind.static;
+  if (source.kind === 'git-native') return SourceKind.gitNative;
+  if (source.kind === 'local' || source.id === 'local') return SourceKind.localSession;
+  return source.kind || SourceKind.draft;
+}
+
+function legacyConfig(source = {}) {
+  const config = {};
+  for (const key of ['repo', 'ref', 'rootPath', 'path', 'permalink', 'remote']) {
+    if (source[key] !== undefined && source[key] !== null && String(source[key]).trim()) config[key] = source[key];
+  }
+  return config;
+}

package/src/sources/source.presenter.js

@@ -0,0 +1,66 @@
+(function attachTiinexSourcePresenter(global) {
+  'use strict';
+
+  function renderWindowHeader(workspace, ctx) {
+    const records = Array.isArray(workspace?.records) ? workspace.records.length : 0;
+    const sources = visibleSources(workspace).length;
+    const drafts = (workspace?.records || []).filter((record) => record.kind === 'continuation' || record.status === 'draft').length;
+    return `<header class="tx-window-titlebar tx-legacy-titlebar tx-v115-workspace-header"><div class="tx-window-identity"><strong>${ctx.escapeHtml(workspace?.name || 'Workspace')}</strong></div><div class="tx-window-stats tx-legacy-counter-bar">${ctx.statPill('database', sources, 'Sources')}${ctx.statPill('file', records, 'Loaded records')}${ctx.statPill('seedling', 0, 'Leaf candidates')}${ctx.statPill('pen', drafts, 'Drafts')}<button class="tx-icon-button tx-old-icon-button" type="button" data-share title="Share workspace">${ctx.icon('shareNodes')}</button><button class="tx-icon-button tx-old-icon-button" type="button" title="Policy / source boundary">${ctx.icon('scale')}</button><button class="tx-icon-button tx-old-icon-button" type="button" data-workspace-action="open" data-workspace-id="${ctx.escapeHtml(workspace.id)}" title="Open workspace summary">${ctx.icon('document')}</button><button class="tx-icon-button tx-old-icon-button tx-download-button" type="button" title="Export/download not available until material exists">${ctx.icon('download')}</button><button class="tx-icon-button tx-old-icon-button tx-add-source-button" type="button" data-workspace-action="add-source" data-workspace-id="${ctx.escapeHtml(workspace.id)}" title="Add material or source">${ctx.icon('create')}</button><button class="tx-icon-button tx-old-icon-button" type="button" title="Expand workspace">${ctx.icon('external')}</button><button class="tx-icon-button tx-old-icon-button" type="button" data-close-workspace="${ctx.escapeHtml(workspace.id)}" title="Close workspace">${ctx.icon('close')}</button></div></header>`;
+  }
+
+  function renderSourceStrip(workspace, ctx) {
+    const sources = visibleSources(workspace);
+    if (!sources.length) return '';
+    return `<div class="workspace-source-strip source-strip-stable tx-legacy-source-strip tx-v115-source-strip" aria-label="Workspace sources">${sources.map((source) => renderSourcePill(workspace, source, ctx)).join('')}</div>`;
+  }
+
+  function renderProgress(workspace, ctx) {
+    const progress = workspace?.discoveryProgress;
+    if (!progress?.active) return '';
+    const percent = Math.max(0, Math.min(100, Number(progress.percent || 0)));
+    return `<div class="loading-progress tx-v115-loading-progress" data-discovery-progress="${ctx.escapeHtml(workspace.id)}" data-progress="${percent}"><div class="progress-head"><span>${ctx.icon('spinner')}<span data-progress-title>${ctx.escapeHtml(progress.label || 'Preparing source')}</span></span><small data-progress-label>${percent}%</small></div><div class="progress-track" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="${percent}"><span class="progress-fill" data-progress-fill style="width:${percent}%"></span></div></div>`;
+  }
+
+  function renderAddSourceDialog(workspace, ctx) {
+    const entry = configuredEntrypoint(ctx.workspaceConfig);
+    const repo = entry.repository || 'Tiinex/docs';
+    return `<div class="tx-dialog-backdrop" role="presentation"><section class="tx-dialog tx-source-dialog" role="dialog" aria-modal="true" aria-labelledby="add-source-title"><button class="tx-dialog-close" type="button" data-dialog-close aria-label="Close">${ctx.icon('close')}</button><div class="tx-mini-label">Source</div><h2 id="add-source-title">Add material or source</h2><p class="tx-muted">Keep local material separate from explicit repository sources. Repository loading is explicit and shown as progress.</p><form id="add-source-form" data-workspace-id="${ctx.escapeHtml(workspace?.id || '')}"><div class="tx-source-choice"><strong>${ctx.escapeHtml(repo)}</strong><span>${ctx.escapeHtml(entry.rootPath || '.topics')} · ${ctx.escapeHtml(entry.ref || 'master')} · Source Pages mirror</span></div><button class="tx-button tx-primary tx-dialog-primary" type="submit">${ctx.icon('github')} Add GitHub source</button></form><div class="tx-dialog-actions tx-source-dialog-actions"><button class="tx-button" type="button" data-workspace-action="add-material" data-workspace-id="${ctx.escapeHtml(workspace?.id || '')}">${ctx.icon('load')} Add local Markdown</button></div></section></div>`;
+  }
+
+  function visibleSources(workspace) {
+    return (Array.isArray(workspace?.sources) ? workspace.sources : [])
+      .map((source) => Object.assign({}, source, { count: Number(source.count || 0) }));
+  }
+
+  function renderSourcePill(workspace, source, ctx) {
+    const local = source.id === 'local' || source.kind === 'local';
+    const originRecovery = source.recoveryOnly === true || source.originReferenceSource === true || source.sourceKind === 'github.origin-reference';
+    const iconName = local ? 'folder' : (source.kind && source.kind.includes('github') ? 'github' : 'link');
+    const closeTitle = local ? 'Clear local/session material' : originRecovery ? 'Dismiss recovery-only origin' : 'Close this source';
+    const closeLabel = local ? 'Clear Local source material from this browser session' : originRecovery ? `Dismiss recovery-only origin ${source.label || source.id}` : `Close source ${source.label || source.id}`;
+    const close = source.closeable ? `<button class="source-close-btn" type="button" data-workspace-id="${ctx.escapeHtml(workspace.id)}" data-close-source="${ctx.escapeHtml(source.id)}" title="${ctx.escapeHtml(closeTitle)}" aria-label="${ctx.escapeHtml(closeLabel)}">${ctx.icon('close')}</button>` : '';
+    const count = originRecovery ? `${Number(source.originReferenceCount || 0)} refs` : Number(source.count || 0);
+    const role = originRecovery ? '<em class="source-role-badge">recovery only</em>' : '';
+    return `<span class="workspace-source-pill ${originRecovery ? 'source-origin-recovery' : local ? 'source-local' : 'source-github'}" title="${ctx.escapeHtml(source.boundary || source.label || 'Source')}">${ctx.icon(iconName)}<span>${ctx.escapeHtml(source.label || source.repo || source.id)}</span><small>${ctx.escapeHtml(count)}</small>${role}${close}</span>`;
+  }
+
+  function configuredEntrypoint(workspaceConfig) {
+    const entry = (workspaceConfig?.workspaceEntrypoints || [])[0] || {};
+    return Object.assign({ label: 'Tiinex/docs', repository: 'Tiinex/docs', ref: 'master', rootPath: '.topics' }, entry);
+  }
+
+  function configuredMirrorLabel(workspaceConfig, repo) {
+    const match = (workspaceConfig?.repositoryMirrors || []).find((mirror) => String(mirror.repository || '').toLowerCase() === String(repo || '').toLowerCase());
+    return match ? 'Source Pages mirror' : 'configured mirror';
+  }
+
+  global.TiinexSourcePresenter = {
+    configuredEntrypoint,
+    configuredMirrorLabel,
+    renderAddSourceDialog,
+    renderProgress,
+    renderSourceStrip,
+    renderWindowHeader,
+    visibleSources
+  };
+})(typeof window !== 'undefined' ? window : globalThis);

package/src/sources/source.resolve.js

@@ -0,0 +1,11 @@
+import { isLocalSource, normalizeSourceRegistration } from './source.model.js';
+
+export function resolveSource(source) {
+  if (!source) return { kind: 'draft', githubPolicy: 'not-guessed' };
+  const normalized = normalizeSourceRegistration(source);
+  if (isLocalSource(normalized)) return { ...normalized, githubPolicy: 'not-guessed' };
+  if (normalized.adapterId === 'github' && !(normalized.repo || normalized.config?.repo || normalized.permalink)) {
+    return { ...normalized, kind: 'draft', githubPolicy: 'not-guessed' };
+  }
+  return { ...normalized, githubPolicy: normalized.adapterId === 'github' ? 'explicit' : 'not-guessed' };
+}

package/src/sources/static/static.source.js

@@ -0,0 +1 @@
+export function staticSource(path) { return { kind: 'static', path }; }

package/src/sources/transport.policy.case.mjs

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import { authorizeSourceTransport, buildSourceTransportPolicy, summarizeSourceTransportOutcomes } from './transport.policy.js';
+
+const policy = buildSourceTransportPolicy({ maxRequestsPerOperation: 2, now: '2026-07-21T10:00:00.000Z' });
+assert.equal(policy.schema, 'tiinex.sourceTransport.policy.v1');
+assert.equal(policy.maxRequestsPerOperation, 2);
+assert(policy.boundary.includes('does not infer provenance'));
+
+const allowed = authorizeSourceTransport({ kind: 'github.raw', sourceId: 'gh', adapterId: 'github', requestedRequests: 2 }, policy);
+assert.equal(allowed.allowed, true);
+assert.equal(allowed.status, 'allowed');
+
+const overBudget = authorizeSourceTransport({ kind: 'github.raw', sourceId: 'gh', adapterId: 'github', requestedRequests: 3 }, policy);
+assert.equal(overBudget.allowed, false);
+assert.equal(overBudget.status, 'blocked');
+assert.equal(overBudget.findings[0].code, 'transport.policy.request-budget-exceeded');
+assert.equal(overBudget.findings[0].retryable, false);
+
+const cooldown = authorizeSourceTransport(
+  { kind: 'github.discovery', sourceId: 'gh', adapterId: 'github', requestedRequests: 1 },
+  { cooldownUntil: '2026-07-21T11:00:00.000Z', now: '2026-07-21T10:00:00.000Z' }
+);
+assert.equal(cooldown.allowed, false);
+assert.equal(cooldown.findings[0].code, 'transport.policy.cooldown-active');
+assert.equal(cooldown.findings[0].retryable, true);
+
+const offline = authorizeSourceTransport({ requestedRequests: 1 }, { offline: true });
+assert.equal(offline.allowed, false);
+assert.equal(offline.findings[0].code, 'transport.policy.offline');
+
+const summary = summarizeSourceTransportOutcomes([allowed, overBudget, cooldown]);
+assert.equal(summary.schema, 'tiinex.sourceTransport.policy.summary.v1');
+assert.equal(summary.status, 'degraded');
+assert.equal(summary.counts.operations, 3);
+assert.equal(summary.counts.allowed, 1);
+assert.equal(summary.counts.blocked, 2);
+assert.equal(summary.counts.retryable, 1);
+
+console.log('source transport policy: ok');

package/src/sources/transport.policy.js

@@ -0,0 +1,81 @@
+export const SOURCE_TRANSPORT_POLICY_SCHEMA_ID = 'tiinex.sourceTransport.policy.v1';
+
+export function buildSourceTransportPolicy(input = {}) {
+  const maxRequestsPerOperation = finitePositive(input.maxRequestsPerOperation, input.maxRequestsPerSource, input.maxRequests) || 0;
+  const cooldownUntil = String(input.cooldownUntil || '').trim();
+  const now = String(input.now || input.at || '').trim();
+  const offline = input.offline === true;
+  return Object.freeze({
+    schema: SOURCE_TRANSPORT_POLICY_SCHEMA_ID,
+    mode: input.mode || (offline ? 'offline' : 'bounded-online'),
+    maxRequestsPerOperation,
+    cooldownUntil,
+    now,
+    offline,
+    boundary: 'Source transport policy only authorizes or blocks fetch attempts. It does not infer provenance, retry in the background, or mutate source state.'
+  });
+}
+
+export function authorizeSourceTransport(operation = {}, policyInput = {}) {
+  const policy = policyInput?.schema === SOURCE_TRANSPORT_POLICY_SCHEMA_ID ? policyInput : buildSourceTransportPolicy(policyInput);
+  const requestedRequests = Math.max(0, Number(operation.requestedRequests || operation.requests || 0));
+  const sourceId = operation.sourceId || operation.source?.id || '';
+  const adapterId = operation.adapterId || operation.source?.adapterId || '';
+  const findings = [];
+  if (policy.offline || policy.mode === 'offline') {
+    findings.push(finding('warning', 'transport.policy.offline', 'Source transport is offline/disabled for this operation.', { sourceId, adapterId, requestedRequests, retryable: true }));
+  }
+  if (policy.cooldownUntil && policy.now && new Date(policy.cooldownUntil).getTime() > new Date(policy.now).getTime()) {
+    findings.push(finding('warning', 'transport.policy.cooldown-active', 'Source transport is in cooldown; do not retry automatically.', { sourceId, adapterId, requestedRequests, retryable: true, cooldownUntil: policy.cooldownUntil }));
+  }
+  if (policy.maxRequestsPerOperation > 0 && requestedRequests > policy.maxRequestsPerOperation) {
+    findings.push(finding('warning', 'transport.policy.request-budget-exceeded', `Requested ${requestedRequests} source request(s), over budget ${policy.maxRequestsPerOperation}.`, { sourceId, adapterId, requestedRequests, maxRequests: policy.maxRequestsPerOperation, retryable: false }));
+  }
+  const allowed = findings.length === 0;
+  return Object.freeze({
+    schema: 'tiinex.sourceTransport.authorization.v1',
+    status: allowed ? 'allowed' : 'blocked',
+    allowed,
+    boundary: policy.boundary,
+    operation: Object.freeze({
+      kind: operation.kind || 'source-transport',
+      sourceId,
+      adapterId,
+      requestedRequests
+    }),
+    policy,
+    findings: Object.freeze(findings)
+  });
+}
+
+export function summarizeSourceTransportOutcomes(outcomes = [], input = {}) {
+  const items = Array.isArray(outcomes) ? outcomes : [];
+  const findings = items.flatMap((outcome) => Array.isArray(outcome.findings) ? outcome.findings : []);
+  const blocked = items.filter((outcome) => outcome.allowed === false || outcome.status === 'blocked').length;
+  const retryable = findings.filter((item) => item.retryable === true).length;
+  return Object.freeze({
+    schema: 'tiinex.sourceTransport.policy.summary.v1',
+    status: blocked ? 'degraded' : 'clean',
+    boundary: 'Policy summary is diagnostic-only and must not trigger hidden retries.',
+    counts: Object.freeze({
+      operations: items.length,
+      allowed: items.length - blocked,
+      blocked,
+      findings: findings.length,
+      retryable
+    }),
+    findings: Object.freeze(findings.slice(0, Number(input.maxFindings || 20)))
+  });
+}
+
+function finitePositive(...values) {
+  for (const value of values) {
+    const n = Number(value || 0);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return 0;
+}
+
+function finding(severity, code, message, extra = {}) {
+  return Object.freeze(Object.assign({ severity, code, message }, extra));
+}

package/src/storage/storage.policy.js

@@ -0,0 +1,79 @@
+export const STORAGE_POLICY_SCHEMA_ID = 'tiinex.storage.policy.v1';
+
+export const DefaultStoragePolicyLimits = Object.freeze({
+  maxRecordMarkdownChars: 160000,
+  maxAssetPreviewChars: 160000,
+  maxWorkspaceMarkdownChars: 160000,
+  maxImportLogEntries: 25
+});
+
+export function classifyRecordPersistence(record = {}, limits = DefaultStoragePolicyLimits) {
+  const markdown = String(record.markdown || '');
+  const local = isLocalRecord(record);
+  const sourceBacked = isSourceBacked(record);
+  if (sourceBacked && !local) return decision('record', 'metadata-only', false, 'source-backed-record-not-session-cache-authority', 0, markdown.length);
+  if (!markdown) return decision('record', 'metadata-only', false, 'no-markdown-content', 0, 0);
+  const limit = Number(limits.maxRecordMarkdownChars || 0);
+  if (limit > 0 && markdown.length > limit) return decision('record', 'truncated', true, 'record-markdown-truncated-for-session-cache', limit, markdown.length);
+  return decision('record', 'full', true, 'local-record-session-cache', markdown.length, markdown.length);
+}
+
+export function classifyAssetPersistence(asset = {}, limits = DefaultStoragePolicyLimits) {
+  const contentLength = String(asset.content || '').length;
+  const dataUrlLength = String(asset.dataUrl || '').length;
+  const previewLength = Math.max(contentLength, dataUrlLength);
+  const sourceBacked = isSourceBacked(asset);
+  if (sourceBacked) return decision('asset', 'metadata-only', false, 'source-backed-asset-reference', 0, previewLength);
+  if (!previewLength) return decision('asset', 'metadata-only', false, 'asset-metadata-only', 0, 0);
+  const limit = Number(limits.maxAssetPreviewChars || 0);
+  if (limit > 0 && previewLength > limit) return decision('asset', 'truncated', true, 'asset-preview-truncated-for-session-cache', limit, previewLength);
+  return decision('asset', 'full', true, 'local-asset-session-cache', previewLength, previewLength);
+}
+
+export function classifyWorkspaceCandidatePersistence(candidate = {}, limits = DefaultStoragePolicyLimits) {
+  const markdown = String(candidate.markdown || '');
+  if (!markdown) return decision('workspace-candidate', 'metadata-only', false, 'workspace-candidate-metadata-only', 0, 0);
+  const limit = Number(limits.maxWorkspaceMarkdownChars || 0);
+  if (limit > 0 && markdown.length > limit) return decision('workspace-candidate', 'truncated', true, 'workspace-markdown-truncated-for-session-cache', limit, markdown.length);
+  return decision('workspace-candidate', 'full', true, 'workspace-candidate-session-cache', markdown.length, markdown.length);
+}
+
+export function summarizeStoragePolicy(workspace = {}, limits = DefaultStoragePolicyLimits) {
+  const records = (workspace.records || []).map((record) => classifyRecordPersistence(record, limits));
+  const assets = (workspace.assets || []).map((asset) => classifyAssetPersistence(asset, limits));
+  const workspaceCandidates = (workspace.workspaceMergeCandidates || []).map((candidate) => classifyWorkspaceCandidatePersistence(candidate, limits));
+  const all = [...records, ...assets, ...workspaceCandidates];
+  return Object.freeze({
+    schema: STORAGE_POLICY_SCHEMA_ID,
+    workspaceId: workspace.id || '',
+    counts: Object.freeze({
+      records: records.length,
+      assets: assets.length,
+      workspaceCandidates: workspaceCandidates.length,
+      full: all.filter((item) => item.persistence === 'full').length,
+      truncated: all.filter((item) => item.persistence === 'truncated').length,
+      metadataOnly: all.filter((item) => item.persistence === 'metadata-only').length,
+      persistedBytes: all.reduce((sum, item) => sum + item.persistedBytes, 0),
+      originalBytes: all.reduce((sum, item) => sum + item.originalBytes, 0)
+    }),
+    records: Object.freeze(records),
+    assets: Object.freeze(assets),
+    workspaceCandidates: Object.freeze(workspaceCandidates)
+  });
+}
+
+function isLocalRecord(record = {}) {
+  const source = record.source || {};
+  const mode = String(record.sourceMode || '').toLowerCase();
+  return source.adapterId === 'local' || source.kind === 'local-session' || mode.startsWith('local-') || mode.includes('fixture');
+}
+
+function isSourceBacked(item = {}) {
+  const source = item.source || {};
+  const mode = String(item.sourceMode || '').toLowerCase();
+  return source.adapterId === 'github' || source.kind === 'github-tree' || source.sourceKind === 'github.repo' || mode === 'source-backed';
+}
+
+function decision(kind, persistence, persistContent, reason, persistedBytes, originalBytes) {
+  return Object.freeze({ kind, persistence, persistContent, reason, persistedBytes, originalBytes });
+}