@tiinex/core 0.1.1

package/src/publication/publication.targetContract.js

@@ -0,0 +1,241 @@
+import {
+  GITHUB_ISSUE_BODY_TARGET_KIND,
+  GITHUB_ISSUE_COMMENT_TARGET_KIND,
+  normalizeGithubRepository,
+  parseExactGithubIssueTarget,
+  sameGithubRepository
+} from '../sources/github/github.issueTarget.js';
+
+export const GITHUB_REPO_FILE_TARGET_KIND = 'github.repo.file';
+export { GITHUB_ISSUE_BODY_TARGET_KIND, GITHUB_ISSUE_COMMENT_TARGET_KIND };
+
+const REPO_FILE_ALIASES = new Set([GITHUB_REPO_FILE_TARGET_KIND, 'github-repo-file']);
+const ISSUE_BODY_ALIASES = new Set([GITHUB_ISSUE_BODY_TARGET_KIND, 'github-issue-body']);
+const ISSUE_COMMENT_ALIASES = new Set([GITHUB_ISSUE_COMMENT_TARGET_KIND, 'github-issue-comment']);
+
+export function normalizePublicationDestination(value = {}) {
+  const provider = String(value.provider || value.adapterId || '').trim().toLowerCase();
+  const targetKind = canonicalTargetKind(value.targetKind || value.surface || '');
+  const exactSocialTarget = provider === 'github' && [GITHUB_ISSUE_BODY_TARGET_KIND, GITHUB_ISSUE_COMMENT_TARGET_KIND].includes(targetKind);
+  const externalTarget = rawTargetAlias(value, ['externalTarget', 'inputTarget', 'url']);
+  const containerTarget = rawTargetAlias(value, ['containerTarget', 'parentTarget', 'issueTarget']);
+  return deepFreeze({
+    provider,
+    repository: String(value.repository || value.repo || '').trim(),
+    ref: String(value.ref || value.branch || '').trim(),
+    path: String(value.path || '').trim().replace(/^\/+/, ''),
+    externalTarget: exactSocialTarget ? externalTarget : externalTarget.trim(),
+    containerTarget: exactSocialTarget ? containerTarget : containerTarget.trim(),
+    targetKind,
+    declaredTargetKind: String(value.targetKind || value.surface || '').trim()
+  });
+}
+
+export function publicationDestinationFindings(destination = {}, mutationPolicy = '') {
+  const findings = [];
+  if (!destination.provider) findings.push(finding('error', 'publication.plan.destination.provider-missing', 'Publication destination requires explicit provider identity.'));
+  if (destination.provider !== 'github') {
+    if (!destination.externalTarget && !destination.path) findings.push(finding('error', 'publication.plan.destination.target-missing', 'Publication destination requires an exact provider target/path.'));
+    return findings;
+  }
+
+  if (!destination.repository) findings.push(finding('error', 'publication.plan.destination.repo-missing', 'GitHub publication destination requires exact repository.'));
+  if (!destination.targetKind) {
+    findings.push(finding('error', 'publication.plan.destination.target-kind-missing', 'GitHub publication destination requires one exact target kind.'));
+    return findings;
+  }
+
+  if (destination.targetKind === GITHUB_REPO_FILE_TARGET_KIND) {
+    if (!destination.ref) findings.push(finding('error', 'publication.plan.destination.ref-missing', 'GitHub repo-file publication requires explicit destination ref/branch.'));
+    if (!destination.path) findings.push(finding('error', 'publication.plan.destination.path-missing', 'GitHub repo-file publication requires exact repo-relative target path.'));
+    return findings;
+  }
+
+  if (destination.targetKind === GITHUB_ISSUE_BODY_TARGET_KIND) {
+    if (!['create-new', 'update-known'].includes(mutationPolicy)) findings.push(finding('error', 'publication.plan.mutation-policy.unsupported-for-target', 'GitHub issue-body publication requires create-new or update-known mutation policy.'));
+    if (mutationPolicy === 'update-known' && !destination.externalTarget) findings.push(finding('error', 'publication.plan.destination.issue-target-missing', 'Updating a known GitHub issue body requires its exact issue URL in the plan.'));
+    if (destination.externalTarget) findings.push(...validateSocialTarget(destination.externalTarget, destination, GITHUB_ISSUE_BODY_TARGET_KIND, 'issue-target'));
+    return findings;
+  }
+
+  if (destination.targetKind === GITHUB_ISSUE_COMMENT_TARGET_KIND) {
+    if (!['create-comment', 'update-known'].includes(mutationPolicy)) findings.push(finding('error', 'publication.plan.mutation-policy.unsupported-for-target', 'GitHub issue-comment publication requires create-comment or update-known mutation policy.'));
+    if (mutationPolicy === 'create-comment' && !destination.containerTarget) findings.push(finding('error', 'publication.plan.destination.container-target-missing', 'Creating a GitHub issue comment requires the exact parent issue URL.'));
+    if (mutationPolicy === 'update-known' && !destination.externalTarget) findings.push(finding('error', 'publication.plan.destination.comment-target-missing', 'Updating a known GitHub issue comment requires its exact comment permalink.'));
+    if (destination.containerTarget) findings.push(...validateSocialTarget(destination.containerTarget, destination, GITHUB_ISSUE_BODY_TARGET_KIND, 'container-target'));
+    if (destination.externalTarget) findings.push(...validateSocialTarget(destination.externalTarget, destination, GITHUB_ISSUE_COMMENT_TARGET_KIND, 'comment-target'));
+    const container = parseExactGithubIssueTarget(destination.containerTarget);
+    const exactComment = parseExactGithubIssueTarget(destination.externalTarget);
+    if (container.ok && exactComment.ok && !sameIssueContainer(exactComment, container)) findings.push(finding('error', 'publication.plan.destination.comment-container-mismatch', 'GitHub comment target belongs to a different issue than the declared publication container.'));
+    return findings;
+  }
+
+  findings.push(finding('error', 'publication.plan.destination.target-kind-unsupported', 'GitHub publication target kind is not supported by the shared contract.', { targetKind: destination.declaredTargetKind || destination.targetKind }));
+  return findings;
+}
+
+export function projectExecutedPublicationTarget(plan = {}, execution = {}) {
+  const supplied = execution.sourceTarget || execution.remoteTarget || {};
+  const destination = plan.destination || {};
+  const plannedTargetKind = canonicalTargetKind(destination.targetKind || '');
+  const suppliedTargetKind = canonicalTargetKind(supplied.targetKind || '');
+  let projection;
+  if (destination.provider === 'github' && plannedTargetKind === GITHUB_REPO_FILE_TARGET_KIND) projection = projectRepoFileTarget(plan, execution, supplied);
+  else if (destination.provider === 'github' && (plannedTargetKind === GITHUB_ISSUE_BODY_TARGET_KIND || plannedTargetKind === GITHUB_ISSUE_COMMENT_TARGET_KIND)) projection = projectGithubSocialTarget(plan, execution, supplied, plannedTargetKind);
+  else projection = projectGenericTarget(plan, execution, supplied, plannedTargetKind);
+  const findings = [...(projection.findings || [])];
+  if (suppliedTargetKind && suppliedTargetKind !== plannedTargetKind) findings.push(finding('error', 'publication.result.target.kind-mismatch', 'Supplied publication result target kind differs from the planned target kind.'));
+  const suppliedAdapter = String(supplied.adapterId || supplied.provider || '').trim().toLowerCase();
+  if (suppliedAdapter && destination.provider && suppliedAdapter !== destination.provider) findings.push(finding('error', 'publication.result.target.provider-mismatch', 'Supplied publication result provider differs from the planned destination provider.'));
+  return deepFreeze({ target: projection.target, findings, qualified: !hasErrors(findings) && publicationTargetQualified(projection.target) });
+}
+
+export function publicationTargetQualified(target = {}) {
+  if (!target?.adapterId) return false;
+  if (target.adapterId === 'github' && target.targetKind === GITHUB_REPO_FILE_TARGET_KIND) return Boolean(target.repo && target.path && target.materializedCommit && target.immutability === 'immutable-materialized-commit');
+  if (target.adapterId === 'github' && [GITHUB_ISSUE_BODY_TARGET_KIND, GITHUB_ISSUE_COMMENT_TARGET_KIND].includes(target.targetKind)) return Boolean(target.repo && target.inputTarget && target.mutability === 'mutable-remote-representation' && target.exactTarget === true);
+  return Boolean(target.inputTarget || target.path);
+}
+
+function projectRepoFileTarget(plan, execution, supplied) {
+  const destination = plan.destination || {};
+  const findings = [];
+  const repo = String(supplied.repo || supplied.repository || destination.repository || '').trim();
+  const path = String(supplied.path || destination.path || '').trim().replace(/^\/+/, '');
+  const materializedCommit = exactCommit(supplied.materializedCommit || supplied.commit || execution.materializedCommit || '');
+  if (!sameGithubRepository(repo, destination.repository)) findings.push(finding('error', 'publication.result.target.repo-mismatch', 'Verified GitHub repo-file target repository differs from the planned destination.'));
+  if (!path || path !== String(destination.path || '').trim().replace(/^\/+/, '')) findings.push(finding('error', 'publication.result.target.path-mismatch', 'Verified GitHub repo-file target path differs from the planned destination path.'));
+  if (!materializedCommit) findings.push(finding('error', 'publication.result.target.commit-missing', 'Verified GitHub repo-file publication requires one exact 40-character materialized commit.'));
+  const target = deepFreeze({
+    schema: 'tiinex.publication.remote-target.v2',
+    adapterId: 'github',
+    repo,
+    configuredRef: String(destination.ref || supplied.configuredRef || supplied.ref || '').trim(),
+    materializedCommit,
+    path,
+    inputTarget: String(supplied.inputTarget || '').trim(),
+    targetKind: GITHUB_REPO_FILE_TARGET_KIND,
+    exactTarget: Boolean(repo && path && materializedCommit),
+    immutability: materializedCommit ? 'immutable-materialized-commit' : 'degraded',
+    mutability: 'immutable-materialized-representation',
+    issueNumber: null,
+    commentId: '',
+    containerTarget: '',
+    providerReceiptId: String(execution.providerReceiptId || supplied.providerReceiptId || '')
+  });
+  return deepFreeze({ target, findings, qualified: !hasErrors(findings) && publicationTargetQualified(target) });
+}
+
+function projectGithubSocialTarget(plan, execution, supplied, targetKind) {
+  const destination = plan.destination || {};
+  const findings = [];
+  const inputTarget = rawTargetAlias(supplied, ['inputTarget', 'externalTarget', 'url']);
+  const parsed = parseExactGithubIssueTarget(inputTarget);
+  if (!parsed.ok) findings.push(finding('error', 'publication.result.social-target.invalid', 'Verified GitHub social publication requires one exact GitHub issue/comment target URL.'));
+  else {
+    if (parsed.targetKind !== targetKind) findings.push(finding('error', 'publication.result.social-target.kind-mismatch', 'Verified GitHub social target surface differs from the planned target kind.'));
+    if (!sameGithubRepository(parsed.repository, destination.repository)) findings.push(finding('error', 'publication.result.target.repo-mismatch', 'Verified GitHub social target repository differs from the planned destination.'));
+    if (targetKind === GITHUB_ISSUE_BODY_TARGET_KIND && destination.externalTarget && plan.mutationPolicy === 'update-known' && !sameExactSocialTarget(parsed, parseExactGithubIssueTarget(destination.externalTarget))) findings.push(finding('error', 'publication.result.social-target.planned-target-mismatch', 'Verified issue target differs from the exact known issue target in the plan.'));
+    if (targetKind === GITHUB_ISSUE_COMMENT_TARGET_KIND) {
+      const container = parseExactGithubIssueTarget(destination.containerTarget);
+      if (container.ok && parsed.ok && !sameIssueContainer(parsed, container)) findings.push(finding('error', 'publication.result.social-target.container-mismatch', 'Verified comment target belongs to a different issue than the declared publication container.'));
+      if (destination.externalTarget && plan.mutationPolicy === 'update-known' && !sameExactSocialTarget(parsed, parseExactGithubIssueTarget(destination.externalTarget))) findings.push(finding('error', 'publication.result.social-target.planned-target-mismatch', 'Verified comment target differs from the exact known comment target in the plan.'));
+    }
+  }
+  const target = deepFreeze({
+    schema: 'tiinex.publication.remote-target.v2',
+    adapterId: 'github',
+    repo: parsed.ok ? parsed.repository : String(supplied.repo || supplied.repository || destination.repository || '').trim(),
+    configuredRef: '',
+    materializedCommit: '',
+    path: '',
+    inputTarget: parsed.ok ? parsed.inputTarget : inputTarget,
+    targetKind,
+    exactTarget: Boolean(parsed.ok && parsed.targetKind === targetKind),
+    immutability: 'mutable-exact-target',
+    mutability: 'mutable-remote-representation',
+    issueNumber: parsed.ok ? parsed.number : null,
+    issueNumberLexeme: parsed.ok ? parsed.issueNumber : '',
+    commentId: parsed.ok ? String(parsed.commentId || '') : '',
+    containerTarget: parsed.ok ? parsed.issueTarget : String(destination.containerTarget || ''),
+    providerReceiptId: String(execution.providerReceiptId || supplied.providerReceiptId || '')
+  });
+  return deepFreeze({ target, findings, qualified: !hasErrors(findings) && publicationTargetQualified(target) });
+}
+
+function projectGenericTarget(plan, execution, supplied, targetKind) {
+  const destination = plan.destination || {};
+  const target = deepFreeze({
+    schema: 'tiinex.publication.remote-target.v2',
+    adapterId: String(supplied.adapterId || destination.provider || '').trim(),
+    repo: String(supplied.repo || supplied.repository || destination.repository || '').trim(),
+    configuredRef: String(destination.ref || supplied.configuredRef || supplied.ref || '').trim(),
+    materializedCommit: '',
+    path: String(supplied.path || destination.path || '').trim().replace(/^\/+/, ''),
+    inputTarget: String(supplied.inputTarget || supplied.externalTarget || destination.externalTarget || '').trim(),
+    targetKind,
+    exactTarget: Boolean(supplied.inputTarget || supplied.externalTarget || supplied.path || destination.externalTarget || destination.path),
+    immutability: 'not-claimed',
+    mutability: 'provider-defined',
+    issueNumber: null,
+    commentId: '',
+    containerTarget: '',
+    providerReceiptId: String(execution.providerReceiptId || supplied.providerReceiptId || '')
+  });
+  const findings = [];
+  if (!publicationTargetQualified(target)) findings.push(finding('error', 'publication.result.verified-target.incomplete', 'Verification claims success but exact source target identity is incomplete.'));
+  return deepFreeze({ target, findings, qualified: !hasErrors(findings) && publicationTargetQualified(target) });
+}
+
+function validateSocialTarget(raw, destination, expectedKind, field) {
+  const parsed = parseExactGithubIssueTarget(raw);
+  if (!parsed.ok) return [finding('error', `publication.plan.destination.${field}.invalid`, 'GitHub social publication target must be one exact supported issue/comment URL.')];
+  const findings = [];
+  if (parsed.targetKind !== expectedKind) findings.push(finding('error', `publication.plan.destination.${field}.kind-mismatch`, 'GitHub social target URL does not match the declared target kind.'));
+  if (destination.repository && !sameGithubRepository(parsed.repository, destination.repository)) findings.push(finding('error', `publication.plan.destination.${field}.repo-mismatch`, 'GitHub social target belongs to a different repository than the declared destination.'));
+  return findings;
+}
+
+
+function rawTargetAlias(value = {}, keys = []) {
+  for (const key of keys) {
+    const candidate = value?.[key];
+    if (candidate !== undefined && candidate !== null && String(candidate) !== '') return String(candidate);
+  }
+  return '';
+}
+
+function canonicalTargetKind(value = '') {
+  const clean = String(value || '').trim().toLowerCase();
+  if (REPO_FILE_ALIASES.has(clean)) return GITHUB_REPO_FILE_TARGET_KIND;
+  if (ISSUE_BODY_ALIASES.has(clean)) return GITHUB_ISSUE_BODY_TARGET_KIND;
+  if (ISSUE_COMMENT_ALIASES.has(clean)) return GITHUB_ISSUE_COMMENT_TARGET_KIND;
+  return clean;
+}
+
+function sameIssueContainer(a = {}, b = {}) {
+  return Boolean(a?.ok && b?.ok && sameGithubRepository(a.repository, b.repository) && exactIssueIdentity(a) === exactIssueIdentity(b));
+}
+
+function exactIssueIdentity(value = {}) {
+  return String(value.issueNumber || value.number || '');
+}
+
+function sameExactSocialTarget(a = {}, b = {}) {
+  if (!sameIssueContainer(a, b) || a.targetKind !== b.targetKind) return false;
+  if (a.targetKind === GITHUB_ISSUE_COMMENT_TARGET_KIND) return String(a.commentId || '') === String(b.commentId || '');
+  return true;
+}
+
+function exactCommit(value = '') {
+  const text = String(value || '').trim();
+  return /^[0-9a-f]{40}$/i.test(text) ? text.toLowerCase() : '';
+}
+function hasErrors(findings = []) { return findings.some((item) => item.severity === 'error'); }
+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/reingest/reingest.plan.js

@@ -0,0 +1,162 @@
+import { buildPublicationPreflight } from '../publication/publication.preflight.js';
+import { buildSourceBoundaryReport, isSourceBacked } from '../diagnostics/sourceBoundary.report.js';
+import { projectPackageSourceReference } from '../export/package.sourceReference.js';
+
+export const REINGEST_PLAN_SCHEMA_ID = 'tiinex.reingest.plan.v1';
+
+export function buildReingestPlan(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 sourceBoundary = input.sourceBoundary || buildSourceBoundaryReport(workspace, { records, assets });
+  const publicationPreflight = input.publicationPreflight || buildPublicationPreflight(workspace, { records, assets, workspaceCandidates });
+  const findings = [];
+  const sourceTargets = records.filter((record) => isSourceBacked(record.source)).map((record) => sourceTargetForRecord(record, findings));
+  const localDraftTargets = (publicationPreflight.publishableLocalDrafts || []).map((record) => localDraftTarget(record));
+  const blockedLocalTargets = (publicationPreflight.blockedLocalDrafts || []).map((record) => blockedLocalTarget(record));
+  const assetTargets = assets.map((asset) => assetTarget(asset, findings));
+  const workspaceCandidateTargets = workspaceCandidates.map((candidate) => workspaceCandidateTarget(candidate, findings));
+
+  for (const finding of sourceBoundary.findings || []) {
+    if (finding.severity === 'error' || finding.code?.includes('ref.unpinned') || finding.code?.includes('path.missing') || finding.code?.includes('repo.missing')) {
+      findings.push(normalizeFinding('source-boundary', finding));
+    }
+  }
+  for (const finding of publicationPreflight.findings || []) {
+    if (finding.severity === 'error' || finding.code?.includes('ref-unpinned') || finding.code?.includes('asset.metadata-only') || finding.code?.includes('workspace-candidate')) {
+      findings.push(normalizeFinding('publication-preflight', finding));
+    }
+  }
+
+  const dedupedFindings = dedupeFindings(findings);
+  const counts = {
+    records: records.length,
+    sourceTargets: sourceTargets.length,
+    pinnedSourceTargets: sourceTargets.filter((target) => target.status === 'pinned').length,
+    exactSourceTargets: sourceTargets.filter((target) => target.status === 'exact').length,
+    degradedSourceTargets: sourceTargets.filter((target) => target.status === 'degraded').length,
+    localDraftTargets: localDraftTargets.length,
+    blockedLocalTargets: blockedLocalTargets.length,
+    assets: assetTargets.length,
+    metadataOnlyAssets: assetTargets.filter((target) => target.status !== 'content-available').length,
+    workspaceCandidates: workspaceCandidateTargets.length,
+    errors: dedupedFindings.filter((finding) => finding.severity === 'error').length,
+    warnings: dedupedFindings.filter((finding) => finding.severity === 'warning').length,
+    findings: dedupedFindings.length
+  };
+  const status = counts.errors ? 'blocked' : counts.warnings || counts.degradedSourceTargets || counts.metadataOnlyAssets || counts.workspaceCandidates || counts.blockedLocalTargets ? 'degraded' : 'ready';
+
+  return Object.freeze({
+    schema: REINGEST_PLAN_SCHEMA_ID,
+    workspaceId: workspace.id || '',
+    title: `Re-ingest plan · ${workspace.title || workspace.name || 'workspace'}`,
+    status,
+    boundary: 'Plan only. Re-ingest may read declared source-backed material and replay local drafts after explicit publication/export; it never guesses missing GitHub provenance.',
+    counts: Object.freeze(counts),
+    sourceTargets: Object.freeze(sourceTargets),
+    localDraftTargets: Object.freeze(localDraftTargets),
+    blockedLocalTargets: Object.freeze(blockedLocalTargets),
+    assetTargets: Object.freeze(assetTargets),
+    workspaceCandidateTargets: Object.freeze(workspaceCandidateTargets),
+    findings: Object.freeze(dedupedFindings)
+  });
+}
+
+function sourceTargetForRecord(record = {}, findings = []) {
+  const target = projectPackageSourceReference(record);
+  const id = record.id || target.path || record.path || record.title || 'record';
+  if (target.adapterId === 'github') {
+    if (!target.repo) findings.push(finding('error', 'reingest.github.repo-missing', 'GitHub re-ingest target is missing repo.', { recordId: id, path: target.path }));
+    if (!target.path && !target.inputTarget) findings.push(finding('error', 'reingest.github.path-missing', 'GitHub re-ingest target is missing exact source artifact target.', { recordId: id, repo: target.repo }));
+    if (!target.materializedCommit) findings.push(finding('warning', 'reingest.github.ref-unpinned', 'GitHub re-ingest target lacks exact materialized commit authority; branch/tag refs remain mutable or unqualified.', { recordId: id, repo: target.repo, path: target.path, configuredRef: target.configuredRef }));
+  }
+  return Object.freeze({
+    id,
+    title: record.title || 'Source-backed artifact',
+    adapterId: target.adapterId,
+    repo: target.repo,
+    ref: target.ref,
+    path: target.path,
+    target,
+    status: target.status === 'pinned-reference' ? 'pinned' : target.status === 'exact-target-reference' ? 'exact' : 'degraded',
+    mode: 'read-existing-source',
+    boundary: 'Source-backed material remains reference-only; exact source-target authority is preserved and never inferred from workspace presentation paths.'
+  });
+}
+
+function localDraftTarget(record = {}) {
+  return Object.freeze({
+    id: record.id || record.path || record.title || '',
+    title: record.title || 'Local draft',
+    path: record.path || '',
+    schemaId: record.schemaId || '',
+    status: 'awaiting-publication-or-export',
+    mode: 'local-draft-result',
+    boundary: 'Local draft can only be re-ingested after explicit publication/export assigns a portable source or package target.'
+  });
+}
+
+function blockedLocalTarget(record = {}) {
+  return Object.freeze({
+    id: record.id || record.path || record.title || '',
+    title: record.title || 'Blocked local material',
+    path: record.path || '',
+    status: 'blocked',
+    reason: record.reason || record.status || 'not-publication-ready',
+    mode: 'local-session-only',
+    boundary: 'Blocked local material stays local/session and must not be treated as source-backed.'
+  });
+}
+
+function assetTarget(asset = {}, findings = []) {
+  const id = asset.id || asset.path || asset.name || 'asset';
+  const metadataOnly = asset.previewState === 'omitted-large' || asset.cacheState === 'preview-truncated-for-session-cache' || (!asset.content && !asset.dataUrl && !asset.text);
+  if (metadataOnly) findings.push(finding('warning', 'reingest.asset.metadata-only', 'Asset does not have full content available for re-ingest; keep as metadata-only or require local reselection.', { assetId: id, path: asset.path || '' }));
+  return Object.freeze({
+    id,
+    name: asset.name || asset.path || 'asset',
+    path: asset.path || '',
+    mediaType: asset.type || asset.mimeType || '',
+    status: metadataOnly ? 'metadata-only' : 'content-available',
+    boundary: asset.source?.boundary || 'Asset boundary follows its intake source; local assets are not source-backed leaves.'
+  });
+}
+
+function workspaceCandidateTarget(candidate = {}, findings = []) {
+  findings.push(finding('info', 'reingest.workspace-candidate.explicit-open-merge-required', 'Workspace candidate must be explicitly opened or merged before it participates in re-ingest.', { workspaceCandidateId: candidate.id || '', path: candidate.path || '' }));
+  return Object.freeze({
+    id: candidate.id || candidate.path || '',
+    title: candidate.title || candidate.path || 'Workspace candidate',
+    path: candidate.path || '',
+    status: 'open-or-merge-required',
+    boundary: 'Workspace files are context candidates, not leaves to publish or re-ingest as artifacts.'
+  });
+}
+
+function normalizeFinding(source, item = {}) {
+  return finding(item.severity || 'info', item.code || 'finding', item.message || String(item.code || 'Finding'), Object.assign({ source }, item.recordId ? { recordId: item.recordId } : {}, item.path ? { path: item.path } : {}, item.repo ? { repo: item.repo } : {}));
+}
+
+function dedupeFindings(items = []) {
+  const seen = new Set();
+  const deduped = [];
+  for (const item of items) {
+    const key = [item.severity, item.code, item.recordId || item.assetId || item.workspaceCandidateId || '', item.path || '', item.repo || ''].join('\u0000');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(item);
+  }
+  return deduped;
+}
+
+function finding(severity, code, message, extra = {}) {
+  return Object.freeze(Object.assign({ severity, code, message }, extra));
+}
+
+function explicitRepo(source = {}) {
+  return String(source.repo || source.repository || source.config?.repo || '').trim();
+}
+
+function explicitRef(source = {}) {
+  return String(source.ref || source.config?.ref || source.resolvedRef || source.commit || '').trim();
+}

package/src/release/plan.mjs

@@ -0,0 +1,28 @@
+import {parseSemver, stableVersion, bumpVersion, recommendRelease} from './policy.mjs';
+export const RELEASE_POLICY = 'tiinex.master-npm-release.v1';
+export function compareVersion(a,b){const x=parseSemver(a),y=parseSemver(b);return x.major-y.major||x.minor-y.minor||x.patch-y.patch;}
+export function releasePlan({pkg,metadata,sourceCommit,messages=[],previousPackage=null}) {
+ if(!/^@tiinex\/[a-z0-9-]+$/.test(pkg.name)||pkg.private===true)throw Error('release.package.invalid');
+ if(!/^[a-f0-9]{40,64}$/.test(sourceCommit))throw Error('release.source-commit.required');
+ const versions=Object.values(metadata?.versions||{});
+ const done=versions.find(v=>(v.tiinexRelease?.sourceCommit||v.gitHead)===sourceCommit && !parseSemver(v.version).prerelease);
+ if(done)return {policy:RELEASE_POLICY,action:'skip',reason:'source-already-published',version:done.version,sourceCommit};
+ const stable=versions.filter(v=>!parseSemver(v.version).prerelease).sort((a,b)=>compareVersion(a.version,b.version));
+ const last=stable.at(-1);const floor=stableVersion(pkg.version);
+ let decision;
+ if(!last)decision={bump:'bootstrap',rawSeverity:'bootstrap',targetVersion:floor,reasons:['First stable version: explicit source package floor.']};
+ else decision=recommendRelease({currentVersion:last.version,previousVersion:last.version,previousPackage:previousPackage||last,currentPackage:pkg,commitMessages:messages});
+ if(compareVersion(floor,decision.targetVersion)>0){decision={...decision,targetVersion:floor,reasons:[...decision.reasons,'Source package version explicitly raises the minimum release version.']};}
+ if(metadata?.versions?.[decision.targetVersion])throw Error('release.version.collision');
+ return {policy:RELEASE_POLICY,action:'publish',name:pkg.name,version:decision.targetVersion,previousVersion:last?.version||null,previousCommit:last?.tiinexRelease?.sourceCommit||last?.gitHead||null,sourceCommit,decision};
+}
+export function assertPublishContext(env,repository) {
+ if(env.GITHUB_ACTIONS!=='true'||!['push','workflow_dispatch'].includes(env.GITHUB_EVENT_NAME)||env.GITHUB_REF!=='refs/heads/master'||env.GITHUB_REPOSITORY!==repository)throw Error('release.master-only: publishing requires this repository on refs/heads/master');
+ if(env.TIINEX_ENABLE_NPM_PUBLISH!=='true')throw Error('release.not-enabled');
+}
+export async function readRegistry(name,{fetcher=globalThis.fetch}={}) {
+ const response=await fetcher(`https://registry.npmjs.org/${encodeURIComponent(name)}`,{headers:{Accept:'application/json'},signal:AbortSignal.timeout(30000)});
+ if(response.status===404)return {name,versions:{}};
+ if(!response.ok)throw Error(`release.registry.failure:${response.status}`);
+ const data=await response.json();if(data.name!==name||!data.versions||typeof data.versions!=='object')throw Error('release.registry.invalid-response');return data;
+}

package/src/release/policy.mjs

@@ -0,0 +1,100 @@
+const RELEASE_MARKER = /(?:\[release:(major|minor|patch)\]|\brelease(?:-intent)?\s*:\s*(major|minor|patch)\b)/ig;
+const BREAKING_MARKER = /(?:^|\n)\s*BREAKING(?: CHANGE|-CHANGE)?\s*:|^[a-z]+(?:\([^\n)]*\))?!:/im;
+const FEATURE_MARKER = /(?:^|\n)\s*feat(?:\([^\n)]*\))?\s*:|\[(?:feature|feat)\]/im;
+
+export function parseSemver(value) {
+  const match = String(value ?? '').trim().match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) throw new Error(`Invalid semantic version: ${value}`);
+  return {major:Number(match[1]),minor:Number(match[2]),patch:Number(match[3]),prerelease:match[4] ?? ''};
+}
+
+export function stableVersion(value) {
+  const parsed=parseSemver(value);
+  return `${parsed.major}.${parsed.minor}.${parsed.patch}`;
+}
+
+export function bumpVersion(value, bump) {
+  const parsed=parseSemver(stableVersion(value));
+  if (bump==='major') return `${parsed.major+1}.0.0`;
+  if (bump==='minor') return `${parsed.major}.${parsed.minor+1}.0`;
+  if (bump==='patch') return `${parsed.major}.${parsed.minor}.${parsed.patch+1}`;
+  throw new Error(`Unsupported bump: ${bump}`);
+}
+
+function strongest(values) {
+  const order={patch:1,minor:2,major:3};
+  return values.reduce((best,value)=>order[value]>order[best] ? value : best,'patch');
+}
+
+function explicitMarkers(messages) {
+  const found=[];
+  for (const message of messages) {
+    RELEASE_MARKER.lastIndex=0;
+    let match;
+    while ((match=RELEASE_MARKER.exec(String(message)))) found.push((match[1]??match[2]).toLowerCase());
+  }
+  return found;
+}
+
+function stableObject(value) {
+  if (value===undefined) return null;
+  if (Array.isArray(value)) return value.map(stableObject);
+  if (value && typeof value==='object') return Object.fromEntries(Object.keys(value).sort().map(key=>[key,stableObject(value[key])]));
+  return value;
+}
+
+function same(a,b){return JSON.stringify(stableObject(a))===JSON.stringify(stableObject(b));}
+
+export function comparePackageSurface(previousPackage,currentPackage) {
+  if (!previousPackage) return {severity:'patch',reasons:[]};
+  const reasons=[]; const severities=[];
+  if (previousPackage.name!==currentPackage.name) { severities.push('major'); reasons.push(`package name changed from ${previousPackage.name} to ${currentPackage.name}`); }
+  if (previousPackage.type!==currentPackage.type) { severities.push('major'); reasons.push(`package module type changed from ${previousPackage.type} to ${currentPackage.type}`); }
+  if (!same(previousPackage.engines?.node,currentPackage.engines?.node)) { severities.push('major'); reasons.push('supported Node engine declaration changed'); }
+  const before=previousPackage.exports??{}; const after=currentPackage.exports??{};
+  for (const key of Object.keys(before)) {
+    if (!(key in after)) { severities.push('major'); reasons.push(`public export removed: ${key}`); }
+    else if (!same(before[key],after[key])) { severities.push('major'); reasons.push(`public export target changed: ${key}`); }
+  }
+  for (const key of Object.keys(after)) if (!(key in before)) { severities.push('minor'); reasons.push(`public export added: ${key}`); }
+  const beforeFiles=Array.isArray(previousPackage.files)?previousPackage.files:[];
+  const afterFiles=Array.isArray(currentPackage.files)?currentPackage.files:[];
+  for (const pattern of beforeFiles) if (!afterFiles.includes(pattern)) { severities.push('major'); reasons.push(`published file pattern removed: ${pattern}`); }
+  for (const pattern of afterFiles) if (!beforeFiles.includes(pattern)) { severities.push('minor'); reasons.push(`published file pattern added: ${pattern}`); }
+  return {severity:severities.length?strongest(severities):'patch',reasons};
+}
+
+export function recommendRelease({currentVersion,previousVersion=null,previousPackage=null,currentPackage,commitMessages=[],override=null}) {
+  const current=parseSemver(currentVersion);
+  if (!previousVersion) {
+    const target=stableVersion(currentVersion);
+    return {bump:'bootstrap',rawSeverity:'bootstrap',targetVersion:target,reasons:[`first stable release from ${currentVersion}`],explicit:false};
+  }
+  const base=stableVersion(previousVersion);
+  const baseParsed=parseSemver(base);
+  if (stableVersion(currentVersion)!==base) throw new Error(`package.json version ${currentVersion} does not share the latest release base ${base}`);
+  if (current.prerelease) throw new Error(`package.json must stay on released stable version ${base} after the first release; found ${currentVersion}`);
+  if (override) {
+    if (!['major','minor','patch'].includes(override)) throw new Error(`Invalid release override: ${override}`);
+    return {bump:override,rawSeverity:override,targetVersion:bumpVersion(base,override),reasons:[`manual --bump ${override} override`],explicit:true};
+  }
+  const markers=explicitMarkers(commitMessages);
+  const explicit=markers.length?strongest(markers):null;
+  const packageChange=comparePackageSurface(previousPackage,currentPackage);
+  const breaking=commitMessages.some(message=>BREAKING_MARKER.test(String(message)));
+  const feature=commitMessages.some(message=>FEATURE_MARKER.test(String(message)));
+  const candidates=[packageChange.severity];
+  const reasons=[...packageChange.reasons];
+  if (breaking) { candidates.push('major'); reasons.push('breaking-change commit marker detected'); }
+  if (feature) { candidates.push('minor'); reasons.push('feature commit marker detected'); }
+  if (explicit) { candidates.push(explicit); reasons.push(`explicit release marker requested ${explicit}`); }
+  let rawSeverity=strongest(candidates);
+  let bump=rawSeverity;
+  const explicitMajor=markers.includes('major');
+  if (baseParsed.major===0 && rawSeverity==='major' && !explicitMajor) {
+    bump='minor';
+    reasons.push('pre-1.0 safety: automatic breaking changes advance the minor version; use [release:major] or --bump major to opt into 1.0.0');
+  }
+  if (!reasons.length) reasons.push('no public-surface or release-intent signal detected; defaulting to patch');
+  return {bump,rawSeverity,targetVersion:bumpVersion(base,bump),reasons,explicit:Boolean(explicit)};
+}

package/src/release/run.mjs

@@ -0,0 +1,74 @@
+import {readFile,writeFile,mkdir,rm,cp,realpath,stat} from 'node:fs/promises';
+import {spawnSync} from 'node:child_process';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {assertPublishContext,readRegistry,releasePlan,compareVersion} from './plan.mjs';
+import {parseSemver} from './policy.mjs';
+const npm=process.platform==='win32'?'npm.cmd':'npm';
+function run(command,args,cwd,{allowFailure=false}={}) {const r=spawnSync(command,args,{cwd,encoding:'utf8',timeout:180000,maxBuffer:32*1024*1024,shell:process.platform==='win32'&&command===npm});if(r.error||(!allowFailure&&r.status!==0))throw Error(`${command} ${args[0]} failed: ${r.error?.message||r.stderr||r.stdout}`);return r;}
+/** Release state is registry metadata, not mutable package.json commits or movable tags.
+ * Staging changes only version metadata. The tested source commit is recorded in the tarball.
+ * Caller may invoke prepare for preview; publish independently rechecks master and digest.
+ */
+export async function runRelease({cwd=process.cwd(),argv=process.argv.slice(2),env=process.env}={}) {
+ cwd=await realpath(cwd);const command=argv[0]||'preview';
+ if(!['preview','prepare','publish','bootstrap'].includes(command))throw Error('Use preview, prepare, publish or bootstrap.');
+ const pkg=JSON.parse(await readFile(path.join(cwd,'package.json'),'utf8'));
+ const policy=JSON.parse(await readFile(path.join(cwd,'.github/release-policy.json'),'utf8'));
+ const repository=policy.repository;
+ if(pkg.repository?.url!==`git+https://github.com/${repository}.git`||!repository.startsWith('Tiinex/'))throw Error('release.repository.mismatch');
+ const git=(args,opts)=>run('git',args,cwd,opts);
+ const head=git(['rev-parse','HEAD']).stdout.trim();
+ if(command==='publish') {
+  assertPublishContext(env,repository);
+  const p=JSON.parse(await readFile(path.join(cwd,'.release/plan.json'),'utf8'));
+  if(p.sourceCommit!==head||env.GITHUB_SHA!==head)throw Error('release.commit-changed');
+  if(p.action==='skip'){console.log(JSON.stringify(p));return p;}
+  const file=path.resolve(cwd,p.file);if(path.dirname(file)!==path.join(cwd,'.release'))throw Error('release.archive-path');
+  const bytes=await readFile(file);if(createHash('sha512').update(bytes).digest('base64')!==p.integrity.slice(7))throw Error('release.archive-tampered');
+  const meta=await readRegistry(pkg.name);const existing=meta.versions[p.version];
+  if(existing){if(existing.dist?.integrity!==p.integrity)throw Error('release.version.collision');console.log('Already published exact archive');return p;}
+  const latest=Object.values(meta.versions).filter(v=>!parseSemver(v.version).prerelease).sort((a,b)=>compareVersion(a.version,b.version)).at(-1);
+  if(latest&&compareVersion(latest.version,p.version)>=0)throw Error('release.newer-version-already-published');
+  const result=run(npm,['publish',file,'--ignore-scripts','--access','public','--tag','latest','--provenance'],cwd,{allowFailure:true});
+  if(result.status!==0){const check=await readRegistry(pkg.name);if(check.versions[p.version]?.dist?.integrity!==p.integrity)throw Error('release.publish.failed: '+result.stderr);}
+  console.log(JSON.stringify({...p,published:true}));return p;
+ }
+ if(command==='prepare') {assertPublishContext(env,repository);if(env.GITHUB_SHA!==head)throw Error('release.checkout-is-not-event-commit');}
+ if(command==='bootstrap' && git(['branch','--show-current']).stdout.trim()!=='master')throw Error('release.bootstrap.master-only');
+ if(git(['status','--porcelain','--untracked-files=no']).stdout.trim())throw Error('release.dirty-source');
+ const metadata=await readRegistry(pkg.name);
+ if(command==='bootstrap'&&Object.keys(metadata.versions).length)throw Error('Package exists: configure OIDC and use the master workflow, not bootstrap.');
+ if(command==='bootstrap') { const check=pkg.scripts?.validate?'validate':pkg.scripts?.check?'check':'test'; run(npm,['run',check],cwd); }
+ const previous=Object.values(metadata.versions).filter(v=>!parseSemver(v.version).prerelease).sort((a,b)=>compareVersion(a.version,b.version)).at(-1);
+ let messages=[], previousCommit=previous?.tiinexRelease?.sourceCommit||previous?.gitHead;
+ if(previous) {
+  if(!previousCommit||!/^[a-f0-9]{40,64}$/.test(previousCommit))throw Error('release.previous-source-unavailable: migrate registry/git baseline explicitly');
+  const ancestor=git(['merge-base','--is-ancestor',previousCommit,head],{allowFailure:true});
+  if(ancestor.status!==0){
+   const superseded=git(['merge-base','--is-ancestor',head,previousCommit],{allowFailure:true});
+   if(superseded.status===0){const skipped={action:'skip',reason:'superseded-master-commit',sourceCommit:head,version:previous.version};await mkdir(path.join(cwd,'.release'),{recursive:true});await writeFile(path.join(cwd,'.release/plan.json'),JSON.stringify(skipped,null,2));return skipped;}
+   throw Error('release.divergent-or-shallow-history: full history containing registry source is required');
+  }
+  messages=git(['log','--format=%B%x00',`${previousCommit}..${head}`]).stdout.split('\0').filter(Boolean);
+ } else messages=git(['log','-1','--format=%B']).stdout.split('\0');
+ const plan=releasePlan({pkg,metadata,sourceCommit:head,messages});
+ if(command==='preview'){console.log(JSON.stringify(plan,null,2));return plan;}
+ const dir=path.join(cwd,'.release');await rm(dir,{recursive:true,force:true});await mkdir(dir);
+ if(plan.action==='skip'){await writeFile(path.join(dir,'plan.json'),JSON.stringify(plan,null,2));console.log(JSON.stringify(plan));return plan;}
+ const stage=path.join(dir,'stage');await mkdir(stage);
+ // Excludes ignored/untracked work by definition, and never uses a dirty worktree.
+ const files=git(['ls-files','-z']).stdout.split('\0').filter(Boolean);
+ for(const rel of files){if(rel.startsWith('.release/')||rel.startsWith('node_modules/')||rel.startsWith('.git/'))continue;const from=path.resolve(cwd,rel),to=path.resolve(stage,rel);if(!to.startsWith(stage+path.sep))throw Error('release.path-escape');await mkdir(path.dirname(to),{recursive:true});await cp(from,to,{dereference:false});}
+ const staged={...pkg,version:plan.version,gitHead:head,tiinexRelease:{policy:plan.policy,sourceCommit:head,sourceTree:git(['rev-parse','HEAD^{tree}']).stdout.trim(),repository,previousVersion:plan.previousVersion}};
+ await writeFile(path.join(stage,'package.json'),JSON.stringify(staged,null,2)+'\n');
+ const lockPath=path.join(stage,'package-lock.json');try{const lock=JSON.parse(await readFile(lockPath,'utf8'));lock.version=plan.version;if(lock.packages?.[''])lock.packages[''].version=plan.version;await writeFile(lockPath,JSON.stringify(lock,null,2)+'\n');}catch(e){if(e.code!=='ENOENT')throw e;}
+ const packed=JSON.parse(run(npm,['pack','--ignore-scripts','--json','--pack-destination',dir],stage).stdout)[0];
+ const receipt={...plan,file:'.release/'+packed.filename,integrity:packed.integrity,bytes:packed.size};
+ await writeFile(path.join(dir,'plan.json'),JSON.stringify(receipt,null,2)+'\n');await rm(stage,{recursive:true,force:true});
+ if(command==='bootstrap') {
+  console.log('One-time manual publication under latest dist-tag; requires npm login and 2FA.');
+  const r=spawnSync(npm,['publish',path.join(cwd,receipt.file),'--ignore-scripts','--access','public','--tag','latest','--provenance=false'],{cwd,stdio:'inherit',shell:process.platform==='win32'});if(r.status!==0)throw Error('release.bootstrap.publish-failed');
+ }
+ console.log(JSON.stringify(receipt,null,2));return receipt;
+}