@tiinex/core 0.1.1

package/src/public/companionResources.js

@@ -0,0 +1,246 @@
+const LAYER_PRECEDENCE = Object.freeze({
+  workspace: 500,
+  site: 400,
+  verse: 300,
+  app: 200,
+  core: 100,
+  other: 0
+});
+
+export const COMPANION_RESOLUTION_SCHEMA_ID = 'tiinex.core.companion-resolution.v1';
+export const COMPANION_PROVIDER_SCHEMA_ID = 'tiinex.core.companion-provider.v1';
+
+export function defineCompanionProvider(input = {}) {
+  const id = text(input.id);
+  if (!id) throw new TypeError('Companion provider id is required.');
+  const layer = text(input.layer || 'other').toLowerCase();
+  const precedence = finite(input.precedence, LAYER_PRECEDENCE[layer] ?? LAYER_PRECEDENCE.other);
+  const resources = freeze((Array.isArray(input.resources) ? input.resources : []).map((resource, index) => normalizeResource(resource, { providerId: id, layer, precedence, index })));
+  return freeze({
+    schema: COMPANION_PROVIDER_SCHEMA_ID,
+    id,
+    layer,
+    precedence,
+    resources,
+    boundary: text(input.boundary || 'data-only companion provider; provider presence does not create Tiinex semantic authority')
+  });
+}
+
+export function resolveCompanionResources(input = {}) {
+  const query = normalizeQuery(input.query || input);
+  const providers = (Array.isArray(input.providers) ? input.providers : []).map((provider) => provider?.schema === COMPANION_PROVIDER_SCHEMA_ID ? provider : defineCompanionProvider(provider));
+  const findings = [];
+  const candidates = [];
+
+  for (const provider of providers) {
+    for (const resource of provider.resources) {
+      if (resource.namespace !== query.namespace || resource.slot !== query.slot) continue;
+      const specificity = resourceSpecificity(resource, query);
+      if (specificity < 0) continue;
+      candidates.push(freeze({ ...resource, specificity }));
+    }
+  }
+
+  candidates.sort(compareCandidates);
+  const bestSpecificity = candidates[0]?.specificity ?? -1;
+  const specificityCandidates = candidates.filter((item) => item.specificity === bestSpecificity);
+  const bestPrecedence = specificityCandidates[0]?.providerPrecedence ?? -Infinity;
+  const finalists = specificityCandidates.filter((item) => item.providerPrecedence === bestPrecedence);
+  const cardinality = query.cardinality || finalists[0]?.cardinality || 'single';
+
+  let status = 'missing';
+  let resources = [];
+  if (!candidates.length) {
+    findings.push(finding('info', 'companion.resource.missing', 'No registered companion resource matched the qualified query.', query));
+  } else if (cardinality === 'multiple') {
+    status = 'resolved';
+    const groups = new Map();
+    for (const candidate of candidates) { const key = candidate.key || candidate.path || candidate.id; const values = groups.get(key) || []; values.push(candidate); groups.set(key, values); }
+    for (const [key, values] of [...groups].sort(([a], [b]) => codePoint(a, b))) {
+      const first = values[0];
+      const tied = stableUnique(values.filter(v => v.specificity === first.specificity && v.providerPrecedence === first.providerPrecedence), resourceIdentity);
+      if (tied.length !== 1) { status = 'ambiguous'; findings.push(finding('error', 'companion.collection.key.ambiguous', 'A collection key has conflicting equally ranked resources.', { key })); }
+      else resources.push(tied[0]);
+    }
+    if (status === 'ambiguous') resources = [];
+  } else {
+    const unique = stableUnique(finalists, resourceIdentity);
+    if (unique.length === 1) {
+      status = 'resolved';
+      resources = unique;
+    } else {
+      status = 'ambiguous';
+      findings.push(finding('error', 'companion.resource.ambiguous', 'More than one same-specificity, same-precedence single-value companion remains. Resolution failed closed.', {
+        namespace: query.namespace,
+        slot: query.slot,
+        candidateCount: unique.length,
+        providerIds: unique.map((item) => item.providerId)
+      }));
+    }
+  }
+
+  const winnerIds = new Set(resources.map(resourceIdentity));
+  const shadowed = candidates.filter((item) => !winnerIds.has(resourceIdentity(item)));
+  return freeze({
+    schema: COMPANION_RESOLUTION_SCHEMA_ID,
+    status,
+    query,
+    resources,
+    candidates,
+    shadowed,
+    findings,
+    receipt: {
+      specificity: bestSpecificity,
+      providerPrecedence: Number.isFinite(bestPrecedence) ? bestPrecedence : null,
+      selectedProviders: [...new Set(resources.map((item) => item.providerId))],
+      shadowedProviders: [...new Set(shadowed.map((item) => item.providerId))]
+    },
+    boundary: 'Specificity resolves before provider precedence. Filename order, import order, repository location and display labels never create authority.'
+  });
+}
+
+export function companionProviderFromWorkspace(workspace = {}, options = {}) {
+  const workspaceId = text(workspace.id || workspace.workspaceId || 'workspace');
+  const records = Array.isArray(workspace.records) ? workspace.records : [];
+  const assets = Array.isArray(workspace.assets) ? workspace.assets : [];
+  const resources = [];
+  const findings = [];
+  const recordsByPath = new Map(records.map((record) => [normPath(record.path || record.id || ''), record]).filter(([path]) => path));
+
+  for (const asset of assets) {
+    const assetPath = normPath(asset.path || asset.id || '');
+    if (!assetPath) continue;
+    const parsed = parseCompanionFilename(assetPath);
+    if (!parsed) continue;
+    let ownerArtifactPath = normPath(asset.ownerArtifactPath || '');
+    if (!ownerArtifactPath) {
+      const siblingCandidates = candidateArtifactPathsForCompanion(assetPath, parsed);
+      const matches = siblingCandidates.filter((path) => recordsByPath.has(path));
+      if (matches.length === 1) ownerArtifactPath = matches[0];
+      else if (matches.length > 1) {
+        findings.push(finding('error', 'companion.workspace.owner.ambiguous', 'Artifact-local companion filename matches more than one loaded artifact candidate.', { workspaceId, assetPath, matches }));
+        continue;
+      }
+    }
+    if (!ownerArtifactPath) continue;
+    if (!recordsByPath.has(ownerArtifactPath)) {
+      findings.push(finding('warning', 'companion.workspace.owner.unloaded', 'Companion declares an artifact owner that is not loaded in the Workspace snapshot.', { workspaceId, assetPath, ownerArtifactPath }));
+      continue;
+    }
+    resources.push({
+      namespace: parsed.namespace,
+      slot: parsed.slot,
+      cardinality: parsed.cardinality,
+      owner: { kind: 'artifact', workspaceId, artifactPath: ownerArtifactPath },
+      path: assetPath,
+      mediaType: text(asset.mediaType || asset.type || mimeFromPath(assetPath)),
+      sha256: text(asset.sha256 || ''),
+      source: freeze({ workspaceId, assetId: text(asset.id || assetPath), sourceMode: text(asset.sourceMode || asset.source?.adapterId || 'workspace') })
+    });
+  }
+  return freeze({ provider: defineCompanionProvider({ id: text(options.id || `workspace:${workspaceId}`), layer: 'workspace', precedence: options.precedence, resources }), findings });
+}
+
+export function parseCompanionFilename(path = '') {
+  const name = normPath(path).split('/').at(-1) || '';
+  const match = name.match(/^(.*)\.([a-z0-9][a-z0-9_-]*)\.([a-z0-9][a-z0-9_-]*)(?:\.(many|multiple))?\.([a-z0-9]+)$/i);
+  if (!match) return null;
+  // The common form is owner.namespace.slot.ext. Optional cardinality token may be
+  // `many`/`multiple`; arbitrary extra tokens are treated as part of the slot so
+  // filenames remain forward-compatible without implicit semantics.
+  let [, ownerStem, namespace, slot, extra, extension] = match;
+  let cardinality = 'single';
+  if (extra && ['many', 'multiple'].includes(extra.toLowerCase())) cardinality = 'multiple';
+  else if (extra) slot = `${slot}.${extra}`;
+  return freeze({ ownerStem, namespace: namespace.toLowerCase(), slot: slot.toLowerCase(), cardinality, extension: extension.toLowerCase() });
+}
+
+function normalizeResource(resource = {}, provider = {}) {
+  const namespace = text(resource.namespace).toLowerCase();
+  const slot = text(resource.slot).toLowerCase();
+  if (!namespace || !slot) throw new TypeError('Companion resource namespace and slot are required.');
+  const owner = normalizeOwner(resource.owner || {});
+  const cardinality = text(resource.cardinality || 'single').toLowerCase() === 'multiple' ? 'multiple' : 'single';
+  const path = normPath(resource.path || '');
+  if (path.split('/').includes('..') || /^(?:[a-z]:|\/)/i.test(text(resource.path))) throw new TypeError('Companion path must be relative and stay inside its provider.');
+  const id = text(resource.id || `${provider.providerId}:${namespace}:${slot}:${ownerIdentity(owner)}:${path || provider.index}`);
+  return freeze({
+    id,
+    key: text(resource.key || ''),
+    namespace,
+    slot,
+    cardinality,
+    owner,
+    path,
+    url: text(resource.url || ''),
+    mediaType: text(resource.mediaType || ''),
+    sha256: text(resource.sha256 || ''),
+    source: resource.source || null,
+    providerId: provider.providerId,
+    providerLayer: provider.layer,
+    providerPrecedence: provider.precedence
+  });
+}
+
+function normalizeOwner(owner = {}) {
+  const kind = text(owner.kind || 'root').toLowerCase();
+  if (kind === 'artifact') return freeze({ kind, workspaceId: text(owner.workspaceId), artifactPath: normPath(owner.artifactPath || owner.path || '') });
+  if (kind === 'schema') return freeze({ kind, schemaId: text(owner.schemaId || owner.id) });
+  if (kind !== 'root') throw new TypeError('Unsupported companion owner kind.');
+  return freeze({ kind: 'root', schemaId: text(owner.schemaId || '') });
+}
+
+function normalizeQuery(input = {}) {
+  const owner = normalizeOwner(input.owner || {});
+  return freeze({
+    namespace: text(input.namespace).toLowerCase(),
+    slot: text(input.slot).toLowerCase(),
+    cardinality: text(input.cardinality).toLowerCase() === 'multiple' ? 'multiple' : text(input.cardinality).toLowerCase() === 'single' ? 'single' : '',
+    owner,
+    schemaLineage: freeze((Array.isArray(input.schemaLineage) ? input.schemaLineage : []).map(text).filter(Boolean))
+  });
+}
+
+function resourceSpecificity(resource, query) {
+  const owner = resource.owner;
+  if (owner.kind === 'artifact') {
+    return query.owner.kind === 'artifact' && owner.workspaceId === query.owner.workspaceId && owner.artifactPath === query.owner.artifactPath ? 1000 : -1;
+  }
+  if (owner.kind === 'schema') {
+    const schemaId = query.owner.kind === 'schema' ? query.owner.schemaId : query.schemaLineage[0] || '';
+    const lineage = query.schemaLineage.length ? query.schemaLineage : schemaId ? [schemaId] : [];
+    const index = lineage.indexOf(owner.schemaId);
+    return index < 0 ? -1 : 800 - index;
+  }
+  return 100;
+}
+
+function compareCandidates(a, b) {
+  return b.specificity - a.specificity || b.providerPrecedence - a.providerPrecedence || codePoint(a.providerId, b.providerId) || codePoint(a.id, b.id);
+}
+
+function candidateArtifactPathsForCompanion(assetPath, parsed) {
+  const parts = normPath(assetPath).split('/');
+  parts.pop();
+  const dir = parts.length ? `${parts.join('/')}/` : '';
+  return [
+    `${dir}${parsed.ownerStem}.trace.md`,
+    `${dir}${parsed.ownerStem}.workspace.md`,
+    `${dir}${parsed.ownerStem}.md`
+  ];
+}
+
+function ownerIdentity(owner) {
+  if (owner.kind === 'artifact') return `${owner.workspaceId}::${owner.artifactPath}`;
+  if (owner.kind === 'schema') return owner.schemaId;
+  return 'root';
+}
+function resourceIdentity(item) { return `${item.providerId}|${item.id}|${item.sha256}|${item.path}|${item.url}`; }
+function stableUnique(items, key) { const seen = new Set(); return items.filter((item) => { const value = key(item); if (seen.has(value)) return false; seen.add(value); return true; }); }
+function normPath(value = '') { return text(value).replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, ''); }
+function mimeFromPath(path) { const ext = normPath(path).split('.').at(-1)?.toLowerCase(); return ({ png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', svg: 'image/svg+xml', json: 'application/json', md: 'text/markdown' })[ext] || 'application/octet-stream'; }
+function finite(value, fallback) { const number = Number(value); return Number.isFinite(number) ? number : fallback; }
+function text(value) { return String(value ?? '').trim(); }
+function codePoint(a, b) { return a < b ? -1 : a > b ? 1 : 0; }
+function finding(severity, code, message, details = {}) { return freeze({ severity, code, message, details }); }
+function freeze(value) { if (Array.isArray(value)) return Object.freeze(value.map(freeze)); if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freeze(item)]))); }

package/src/public/index.js

@@ -0,0 +1,16 @@
+export { parseArtifactMarkdown, parseContinuityEnvelope, parseBody, parseIntegrity } from '../artifacts/artifact.parse.js';
+export {
+  APPLICATION_DATA_SCHEMA_ID,
+  projectApplicationData,
+  toPlaythingsStoryRecords
+} from './applicationProjection.js';
+export {
+  COMPANION_PROVIDER_SCHEMA_ID,
+  COMPANION_RESOLUTION_SCHEMA_ID,
+  defineCompanionProvider,
+  resolveCompanionResources,
+  companionProviderFromWorkspace,
+  parseCompanionFilename
+} from './companionResources.js';
+
+export { projectSchemaAncestry } from './schemaAncestry.js';

package/src/public/node.js

@@ -0,0 +1,2 @@
+export * from './index.js';
+export * from '../tooling/portable/index.js';

package/src/public/schemaAncestry.js

@@ -0,0 +1,26 @@
+/** Traverses explicit schema declarations supplied by a qualified host/provider.
+ * Presence in this array is NOT independent schema-authority qualification. */
+export function projectSchemaAncestry(schemaId, declarations = []) {
+  const groups = new Map();
+  for (const declaration of declarations) {
+    if (!declaration?.id) continue;
+    const values = groups.get(declaration.id) || [];
+    values.push(declaration); groups.set(declaration.id, values);
+  }
+  const lineage = [], seen = new Set(); let current = String(schemaId || '');
+  const done = (status, reason) => Object.freeze({ status, reason, lineage: Object.freeze([...lineage]), basis: 'explicit-provider-schema-parent-declarations' });
+  if (!current) return done('unresolved', 'schema-id-missing');
+  while (current) {
+    if (seen.has(current)) return done('cycle', 'schema-parent-cycle');
+    seen.add(current); lineage.push(current);
+    const values = groups.get(current) || [];
+    if (!values.length) return done('unresolved', 'schema-parent-not-loaded');
+    const parents = new Set(values.map(v => Object.hasOwn(v, 'parentSchemaId') ? v.parentSchemaId : undefined));
+    if (parents.size !== 1) return done('ambiguous', 'conflicting-schema-parent-declarations');
+    const parent = [...parents][0];
+    if (parent === null || parent === '') return done('resolved', 'explicit-schema-root');
+    if (typeof parent !== 'string') return done('unresolved', 'schema-parent-not-declared');
+    current = parent;
+  }
+  return done('unresolved', 'schema-parent-not-declared');
+}

package/src/publication/publication.contract.js

@@ -0,0 +1,196 @@
+import { buildPublicationPreflight } from './publication.preflight.js';
+import { isSourceBacked } from '../diagnostics/sourceBoundary.report.js';
+import { projectPackageSourceReference } from '../export/package.sourceReference.js';
+import { sha256Hex, utf8Bytes } from '../export/package.bytes.js';
+import { normalizePublicationDestination, projectExecutedPublicationTarget, publicationDestinationFindings, publicationTargetQualified } from './publication.targetContract.js';
+
+export const PUBLICATION_PLAN_SCHEMA_ID = 'tiinex.publication.plan.v1';
+export const PUBLICATION_RESULT_SCHEMA_ID = 'tiinex.publication.result.v1';
+export const PUBLICATION_RECEIPT_SCHEMA_ID = 'tiinex.publication.receipt.v1';
+
+export function buildPublicationPlan(workspace = {}, input = {}) {
+  const records = Array.isArray(input.records) ? input.records : (Array.isArray(workspace.records) ? workspace.records : []);
+  const preflight = input.preflight || buildPublicationPreflight(workspace, { records, assets: input.assets || workspace.assets || [] });
+  const record = input.record || findRecord(records, input.recordId || input.path || '');
+  const findings = [];
+  if (!record) findings.push(finding('error', 'publication.plan.input.missing', 'Publication plan requires one exact local-owned input record.'));
+  if (record && isSourceBacked(record.source || {})) findings.push(finding('error', 'publication.plan.input.source-backed', 'Source-backed material is reference-only and cannot become a mutable local publication payload without an explicit derived local draft.', { recordId: record.id || '' }));
+  const candidate = record ? (preflight.publishableLocalDrafts || []).find((item) => item.id === record.id || item.path === record.path) : null;
+  if (record && !candidate) findings.push(finding('error', 'publication.plan.input.not-preflight-qualified', 'Local input is not qualified by current publication preflight.', { recordId: record.id || '', path: record.path || '' }));
+
+  const destination = normalizePublicationDestination(input.destination || {});
+  const mutationPolicy = String(input.mutationPolicy || '').trim();
+  if (!mutationPolicy) findings.push(finding('error', 'publication.plan.mutation-policy.missing', 'Publication plan requires an explicit mutation policy; host execution must not infer create/update/replace behavior.'));
+  findings.push(...publicationDestinationFindings(destination, mutationPolicy));
+  const markdown = String(record?.markdown || '');
+  const payloadBytes = utf8Bytes(markdown);
+  const payload = deepFreeze({
+    mediaType: 'text/markdown',
+    bytes: payloadBytes.byteLength,
+    sha256: sha256Hex(payloadBytes),
+    representation: 'exact-local-markdown',
+    content: markdown
+  });
+  const localInput = deepFreeze({
+    id: String(record?.id || ''),
+    title: String(record?.title || ''),
+    path: String(record?.path || ''),
+    schemaId: String(record?.schemaId || record?.currentSchemaId || ''),
+    sourceMode: String(record?.sourceMode || ''),
+    ownership: record && !isSourceBacked(record.source || {}) ? 'owned-local' : 'not-owned-local',
+    sourceUnchangedGuarantee: true
+  });
+  const verification = deepFreeze({
+    required: true,
+    requirement: 'provider-read-after-write-exact-representation',
+    expectedPayloadSha256: payload.sha256,
+    boundary: 'Host adapter must return exact post-write source identity and verification evidence; a transport success alone is not a durable source binding.'
+  });
+  const errors = findings.filter((item) => item.severity === 'error').length;
+  const status = errors ? 'blocked' : 'ready';
+  const identitySeed = {
+    localInput: { id: localInput.id, path: localInput.path },
+    destination,
+    mutationPolicy,
+    payload: { bytes: payload.bytes, sha256: payload.sha256 },
+    verification: { required: verification.required, requirement: verification.requirement }
+  };
+  const planSha256 = sha256Hex(utf8Bytes(stableJson(identitySeed)));
+  return deepFreeze({
+    schema: PUBLICATION_PLAN_SCHEMA_ID,
+    planId: `publication-plan:${planSha256.slice(0, 24)}`,
+    status,
+    boundary: 'Platform-neutral publication plan only. It performs no remote write, credential lookup, UI confirmation, local-source mutation, or automatic provenance assignment.',
+    workspaceId: String(workspace.id || ''),
+    localInput,
+    destination,
+    mutationPolicy,
+    outboundPayload: payload,
+    verification,
+    guarantees: [
+      'The local draft identity remains distinct from the publication operation and remote target identity.',
+      'The local input/source state is not mutated by this plan.',
+      'A successful host write without exact post-write verification does not create a durable source binding.'
+    ],
+    planSha256,
+    findings
+  });
+}
+
+export function buildPublicationResult(plan = {}, execution = {}) {
+  const findings = [...(plan.findings || [])];
+  if (plan.status !== 'ready') findings.push(finding('error', 'publication.result.plan-not-ready', 'Publication result cannot qualify success from a blocked publication plan.'));
+  const executionState = normalizeExecutionState(execution.state || execution.status || '');
+  if (!executionState) findings.push(finding('error', 'publication.result.execution-state.invalid', 'Publication result requires explicit success, failure, or partial execution state.'));
+  const verificationState = normalizeVerificationState(execution.verification?.status || execution.verificationStatus || '');
+  const targetProjection = projectExecutedPublicationTarget(plan, execution);
+  const exactTarget = targetProjection.target;
+  if (verificationState === 'verified') findings.push(...(targetProjection.findings || []));
+  const hostWriteSucceeded = executionState === 'success' || executionState === 'partial';
+  if (hostWriteSucceeded && verificationState !== 'verified') findings.push(finding('warning', 'publication.result.verification.incomplete', 'Host write is not durably source-qualified until exact post-write verification succeeds.'));
+  if (executionState === 'success' && verificationState !== 'verified') findings.push(finding('error', 'publication.result.success-without-verification', 'Publication success cannot be claimed without required exact post-write verification.'));
+  if (verificationState === 'verified' && !publicationTargetQualified(exactTarget)) findings.push(finding('error', 'publication.result.verified-target.incomplete', 'Verification claims success but exact publication target identity is incomplete for the declared target surface.'));
+  if (verificationState === 'verified' && !String(execution.verifiedPayloadSha256 || '').trim()) findings.push(finding('error', 'publication.result.payload-verification.missing', 'Exact verification requires the verified remote payload SHA-256; target existence alone is insufficient.'));
+  if (verificationState === 'verified' && execution.verifiedPayloadSha256 && execution.verifiedPayloadSha256 !== plan.outboundPayload?.sha256) findings.push(finding('error', 'publication.result.payload-verification.mismatch', 'Verified remote payload digest differs from the exact planned outbound payload.'));
+  const verificationEvidence = deepFreeze({
+    source: 'supplied-host-observation',
+    method: String(execution.verification?.method || execution.verificationMethod || (verificationState === 'verified' ? 'exact-payload-sha256-observation' : '')).trim(),
+    observedAt: String(execution.verification?.observedAt || execution.verifiedAt || execution.observedAt || '').trim(),
+    observedTarget: exactTarget,
+    payloadSha256: String(execution.verifiedPayloadSha256 || '').trim(),
+    providerReceiptId: String(execution.providerReceiptId || exactTarget?.providerReceiptId || '').trim(),
+    note: String(execution.verification?.note || execution.verificationNote || '').trim()
+  });
+
+  const errors = findings.filter((item) => item.severity === 'error').length;
+  const warnings = findings.filter((item) => item.severity === 'warning').length;
+  const qualifiedSuccess = !errors && executionState === 'success' && verificationState === 'verified' && publicationTargetQualified(exactTarget);
+  const status = qualifiedSuccess ? 'success' : (executionState === 'failure' || errors ? 'failure' : 'partial');
+  const sourceBinding = qualifiedSuccess ? deepFreeze({
+    schema: 'tiinex.publication.source-binding.v1',
+    localInputId: String(plan.localInput?.id || ''),
+    publicationPlanId: String(plan.planId || ''),
+    remoteTarget: exactTarget,
+    payloadSha256: String(plan.outboundPayload?.sha256 || ''),
+    targetKind: String(exactTarget?.targetKind || ''),
+    mutability: String(exactTarget?.mutability || ''),
+    verificationEvidence,
+    verified: true,
+    boundary: 'Post-publication source binding records the new exact remote representation without mutating or re-identifying the local draft.'
+  }) : null;
+  const resultIdentity = {
+    planId: plan.planId || '',
+    status,
+    executionState,
+    verificationState,
+    remoteTarget: exactTarget,
+    payloadSha256: plan.outboundPayload?.sha256 || ''
+  };
+  const resultSha256 = sha256Hex(utf8Bytes(stableJson(resultIdentity)));
+  const receipt = deepFreeze({
+    schema: PUBLICATION_RECEIPT_SCHEMA_ID,
+    receiptId: `publication-receipt:${resultSha256.slice(0, 24)}`,
+    planId: String(plan.planId || ''),
+    planSha256: String(plan.planSha256 || ''),
+    status,
+    executionState,
+    verificationState,
+    localInputId: String(plan.localInput?.id || ''),
+    inputSourceUnchanged: true,
+    outboundPayloadSha256: String(plan.outboundPayload?.sha256 || ''),
+    verifiedPayloadSha256: String(execution.verifiedPayloadSha256 || ''),
+    verificationEvidence,
+    remoteTarget: exactTarget,
+    sourceBinding,
+    remoteWritePerformed: hostWriteSucceeded,
+    boundary: 'Receipt describes supplied host execution evidence only. This shared contract does not perform the host write and does not turn the local draft into the remote source artifact.'
+  });
+
+  return deepFreeze({
+    schema: PUBLICATION_RESULT_SCHEMA_ID,
+    resultId: `publication-result:${resultSha256.slice(0, 24)}`,
+    status,
+    boundary: 'Platform-neutral publication result over explicitly supplied adapter execution evidence; no remote execution occurs in this module.',
+    planId: String(plan.planId || ''),
+    executionState,
+    verification: {
+      required: Boolean(plan.verification?.required),
+      status: verificationState || 'not-run',
+      expectedPayloadSha256: String(plan.outboundPayload?.sha256 || ''),
+      verifiedPayloadSha256: String(execution.verifiedPayloadSha256 || ''),
+      evidence: verificationEvidence
+    },
+    localInput: plan.localInput || null,
+    remoteTarget: exactTarget,
+    sourceBinding,
+    receipt,
+    counts: { errors, warnings, findings: findings.length },
+    findings
+  });
+}
+
+function findRecord(records = [], key = '') {
+  const clean = String(key || '').trim();
+  return records.find((record) => record === key || String(record.id || '') === clean || String(record.path || '') === clean) || null;
+}
+function normalizeExecutionState(value = '') {
+  const clean = String(value || '').trim().toLowerCase();
+  return ['success', 'failure', 'partial'].includes(clean) ? clean : '';
+}
+function normalizeVerificationState(value = '') {
+  const clean = String(value || '').trim().toLowerCase();
+  return ['verified', 'failed', 'not-run', 'unavailable'].includes(clean) ? clean : '';
+}
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
+}
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}

package/src/publication/publication.preflight.js

@@ -0,0 +1,159 @@
+import { runAudit } from '../audit/audit.run.js';
+import { buildSourceBoundaryReport, isSourceBacked } from '../diagnostics/sourceBoundary.report.js';
+import { projectPackageSourceReference } from '../export/package.sourceReference.js';
+
+export const PUBLICATION_PREFLIGHT_SCHEMA_ID = 'tiinex.publication.preflight.v1';
+
+export function buildPublicationPreflight(workspace = {}, input = {}) {
+  const records = Array.isArray(input.records) ? input.records : (Array.isArray(workspace.records) ? workspace.records : []);
+  const assets = Array.isArray(input.assets) ? input.assets : (Array.isArray(workspace.assets) ? workspace.assets : []);
+  const workspaceCandidates = Array.isArray(input.workspaceCandidates) ? input.workspaceCandidates : (Array.isArray(workspace.workspaceMergeCandidates) ? workspace.workspaceMergeCandidates : []);
+  const boundary = buildSourceBoundaryReport(workspace, { records, assets });
+  const findings = [...(boundary.findings || []).map((finding) => Object.assign({ source: 'source-boundary' }, finding))];
+  const publishable = [];
+  const blockedRecords = [];
+  const sourceReferences = [];
+
+  for (const record of records) {
+    const sourceBacked = isSourceBacked(record.source);
+    if (sourceBacked) {
+      sourceReferences.push(sourceReferenceForRecord(record, findings));
+      continue;
+    }
+    const assessment = assessLocalPublishCandidate(record);
+    if (assessment.publishable) publishable.push(assessment.record);
+    else blockedRecords.push(assessment.record);
+    findings.push(...assessment.findings);
+  }
+
+  for (const asset of assets) assessAssetForPublication(asset, findings);
+  for (const candidate of workspaceCandidates) {
+    findings.push(finding('info', 'publication.workspace-candidate.reference-only', 'Workspace candidate requires explicit Open/Merge before publication; it is not treated as a leaf.', { path: candidate.path || '', workspaceCandidateId: candidate.id || '' }));
+  }
+
+  if (!publishable.length) {
+    findings.push(finding('warning', 'publication.no-local-draft-candidates', 'No local draft leaves are currently ready for publication. Source-backed material remains reference-only.', { workspaceId: workspace.id || '' }));
+  }
+
+  const errors = findings.filter((item) => item.severity === 'error').length;
+  const warnings = findings.filter((item) => item.severity === 'warning').length;
+  const status = errors ? 'blocked' : warnings ? 'degraded' : 'ready';
+
+  return Object.freeze({
+    schema: PUBLICATION_PREFLIGHT_SCHEMA_ID,
+    workspaceId: workspace.id || '',
+    title: `Publication preflight · ${workspace.title || workspace.name || 'workspace'}`,
+    status,
+    boundary: 'Preflight only. No commit, issue, upload, or remote mutation is performed; local drafts stay local until an explicit publication action exists.',
+    counts: Object.freeze({
+      records: records.length,
+      publishableLocalDrafts: publishable.length,
+      blockedLocalDrafts: blockedRecords.length,
+      sourceReferences: sourceReferences.length,
+      assets: assets.length,
+      workspaceCandidates: workspaceCandidates.length,
+      errors,
+      warnings,
+      findings: findings.length
+    }),
+    publishableLocalDrafts: Object.freeze(publishable),
+    blockedLocalDrafts: Object.freeze(blockedRecords),
+    sourceReferences: Object.freeze(sourceReferences),
+    sourceBoundary: boundary,
+    findings: Object.freeze(findings)
+  });
+}
+
+function assessLocalPublishCandidate(record = {}) {
+  const findings = [];
+  const id = record.id || record.path || record.title || 'record';
+  const markdown = String(record.markdown || '').trim();
+  if (!markdown) {
+    findings.push(finding('error', 'publication.local-record.no-markdown', 'Local draft has no Markdown body to publish.', { recordId: id, path: record.path || '' }));
+    return { publishable: false, record: candidateSummary(record, 'blocked', 'no-markdown'), findings };
+  }
+  let audit;
+  try {
+    audit = runAudit({ markdown });
+  } catch (error) {
+    findings.push(finding('error', 'publication.local-record.audit-exception', error?.message || 'Local draft audit failed.', { recordId: id, path: record.path || '' }));
+    return { publishable: false, record: candidateSummary(record, 'blocked', 'audit-exception'), findings };
+  }
+  const missing = requiredEnvelopeFields(markdown);
+  for (const field of missing) {
+    findings.push(finding('error', `publication.local-record.missing-${field.code}`, `Local draft is missing ${field.label}.`, { recordId: id, path: record.path || '' }));
+  }
+  const auditErrors = Number(audit.summary?.error || 0);
+  const auditWarnings = Number(audit.summary?.warning || 0);
+  // v477: semantic contract validity is disclosed but is not itself publication/export readiness.
+  // Publication may preserve/re-home readable local bytes even when reopened semantic validation is incomplete.
+  // Envelope/readability failures remain blocking through the explicit publication checks above.
+  if (auditErrors) {
+    findings.push(finding('info', 'publication.local-record.semantic-contract-invalid', `Local draft currently has ${auditErrors} semantic/audit error${auditErrors === 1 ? '' : 's'}; publication readiness is assessed separately and does not upgrade contract validity.`, { recordId: id, path: record.path || '' }));
+  } else if (auditWarnings) {
+    findings.push(finding('info', 'publication.local-record.semantic-contract-degraded', `Local draft currently has ${auditWarnings} semantic/audit warning${auditWarnings === 1 ? '' : 's'}; publication readiness is assessed separately.`, { recordId: id, path: record.path || '' }));
+  }
+  const publishable = !missing.length;
+  return {
+    publishable,
+    record: candidateSummary(record, publishable ? 'ready' : 'blocked', publishable ? 'schema-envelope-ready' : 'audit-or-envelope-failed', audit),
+    findings
+  };
+}
+
+function requiredEnvelopeFields(markdown = '') {
+  const text = String(markdown || '');
+  const fields = [
+    ['envelope-schema', 'Envelope Schema', /Envelope Schema\s*:/i],
+    ['current-schema', 'Current Schema', /Current Schema\s*:/i],
+    ['current-created-at', 'Current Created At', /-\s*Current[\s\S]*?Created At\s*:/i],
+    ['continuity-integrity', 'Continuity Integrity', /Continuity Integrity/i]
+  ];
+  return fields.filter(([, , pattern]) => !pattern.test(text)).map(([code, label]) => ({ code, label }));
+}
+
+function assessAssetForPublication(asset = {}, findings = []) {
+  if (asset.previewState === 'omitted-large' || asset.cacheState === 'preview-truncated-for-session-cache') {
+    findings.push(finding('warning', 'publication.asset.metadata-only', 'Asset content/preview is not fully available in session cache; package/export must mark it unavailable or require source file selection.', { assetId: asset.id || asset.path || '', path: asset.path || '' }));
+  }
+}
+
+function sourceReferenceForRecord(record = {}, findings = []) {
+  const target = projectPackageSourceReference(record);
+  const id = record.id || record.path || record.title || 'record';
+  if (target.adapterId === 'github') {
+    if (!target.repo) findings.push(finding('error', 'publication.source-reference.repo-missing', 'GitHub source reference is missing repo.', { recordId: id, path: target.path || '' }));
+    if (!target.materializedCommit) findings.push(finding('warning', 'publication.source-reference.ref-unpinned', 'GitHub source reference has no immutable materialized commit; re-ingest must preserve it as degraded even when a branch/tag ref exists.', { recordId: id, path: target.path || '', repo: target.repo || '', ref: target.configuredRef || '' }));
+    if (!target.path && !target.inputTarget) findings.push(finding('error', 'publication.source-reference.path-missing', 'GitHub source reference is missing exact repo-file or issue/comment target identity.', { recordId: id, repo: target.repo || '' }));
+  } else if (!target.inputTarget) {
+    findings.push(finding('warning', 'publication.source-reference.target-degraded', 'External source reference has no exact input target and remains degraded.', { recordId: id, path: target.path || '' }));
+  }
+  return Object.freeze({
+    id,
+    title: record.title || 'Source-backed artifact',
+    path: target.path || String(record.path || ''),
+    adapterId: target.adapterId,
+    repo: target.repo,
+    ref: target.ref,
+    status: target.status,
+    target,
+    writePolicy: 'reference-only; do not publish over source-backed input without explicit derived local draft'
+  });
+}
+
+function candidateSummary(record = {}, status = 'unknown', reason = '', audit = null) {
+  return Object.freeze({
+    id: record.id || record.path || record.title || '',
+    title: record.title || 'Untitled artifact',
+    path: record.path || '',
+    status,
+    reason,
+    schemaId: audit?.artifact?.schemaId || record.schemaId || record.currentSchemaId || '',
+    auditStatus: audit?.status || '',
+    sourceMode: record.sourceMode || ''
+  });
+}
+
+function finding(severity, code, message, extra = {}) {
+  return Object.freeze(Object.assign({ severity, code, message }, extra));
+}