b2c-app-builder 0.221.39

package/kernel/composition/worker-context.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import type { CatalogWorkflowNode, NodeReference } from "../engine/compile.js";
+
+export type WorkerSourceIdentities = Readonly<Record<string, { origin: "package" | "workspace"; sha256?: string }>>;
+/** Package bytes are identity; their installation directory is not. Workspace prompts retain authored path authority. */
+export function workerContextDescriptor(workflow: CatalogWorkflowNode, sources: WorkerSourceIdentities = {}) {
+  const reference = (ref: NodeReference) => ({
+    id: ref.id,
+    path: ref.path,
+    title: ref.title,
+    loadWhen: ref.loadWhen,
+    sha256: ref.resource?.sha256 ?? sources[ref.path]?.sha256,
+    freshness: ref.freshness,
+    sectionId: ref.sectionId,
+    revision: ref.revision,
+    reviewDueBy: ref.reviewDueBy,
+  });
+  const role = workflow.role;
+  const prompt = (location: string) => {
+    const sha256 = role?.promptResources?.[location] ?? (sources[location]?.origin === "package" ? sources[location]?.sha256 : undefined);
+    return sha256 ? { origin: "package", sha256 } : { origin: "workspace", path: location };
+  };
+  return {
+    workflowId: workflow.id,
+    actionClass: workflow.actionClass,
+    protectedCategory: workflow.protectedCategory,
+    instructions: workflow.instructions ?? "",
+    providerIds: [...(workflow.providerIds ?? [])].sort(),
+    references: (workflow.references ?? []).map(reference),
+    role: role
+      ? {
+          id: role.id,
+          name: role.name,
+          prompt: prompt(role.promptPath),
+          parents: role.parentPromptPaths.map(prompt),
+          contextPacks: role.contextPacks.map((pack) => ({ id: pack.id, title: pack.title, references: pack.references.map(reference) })),
+          skillRoutes: role.skillRoutes,
+          toolRoutes: role.toolRoutes,
+          reviewedBy: role.reviewedBy,
+        }
+      : undefined,
+  };
+}
+export function workerContextFingerprint(workflow: CatalogWorkflowNode, sources?: WorkerSourceIdentities): `sha256:${string}` {
+  return `sha256:${createHash("sha256")
+    .update(JSON.stringify(workerContextDescriptor(workflow, sources)))
+    .digest("hex")}`;
+}
+
+/** The snapshot owns these declarations; an equal digest field alone cannot replace authored guidance. */
+export function assertWorkerContext(
+  workflow: CatalogWorkflowNode,
+  context: { workflowId: string; instructions: string; providerIds: readonly string[]; contextFingerprint: string } | undefined,
+): void {
+  if (
+    !context ||
+    context.workflowId !== workflow.id ||
+    context.instructions !== (workflow.instructions ?? "") ||
+    JSON.stringify([...context.providerIds].sort()) !== JSON.stringify([...(workflow.providerIds ?? [])].sort()) ||
+    context.contextFingerprint !== workerContextFingerprint(workflow)
+  )
+    throw Error("binding.worker_context_replacement_required");
+}

package/kernel/context/budget.ts

@@ -0,0 +1,16 @@
+import type { ContextBudget } from "./receipt.js";
+
+export const DEFAULT_CONTEXT_BUDGET: ContextBudget = { maxBytes: 32_000, maxTokens: 8_000 };
+
+export function measureBytes(text: string): number {
+  return Buffer.byteLength(text, "utf8");
+}
+
+// An approximation, not an exact count: chars/4 undercounts code and non-English text against
+// Claude's real tokenizer. The 1.25x margin keeps a budget check from under-reserving on exactly
+// the content types this repo's knowledge base is full of. For an exact count before a hard
+// budget decision, use Anthropic's token-counting endpoint:
+// https://platform.claude.com/docs/en/build-with-claude/token-counting
+export function measureTokens(text: string): number {
+  return Math.ceil((text.length / 4) * 1.25);
+}

package/kernel/context/compile.ts

@@ -0,0 +1,66 @@
+import type { KnowledgeSection, RouteDecision, RouteRequest } from "../routing/types.js";
+import { DEFAULT_CONTEXT_BUDGET, measureBytes, measureTokens } from "./budget.js";
+import { ContextCompileError, type ContextBudget, type ContextCapsule } from "./receipt.js";
+import { selectSections } from "./selectors.js";
+
+export function compileContext(input: {
+  request: RouteRequest;
+  decision: RouteDecision;
+  sections: readonly KnowledgeSection[];
+  liveRevisions: Record<string, string>;
+  budget?: ContextBudget;
+}): ContextCapsule {
+  if (input.decision.outcome !== "selected" || !input.decision.selectedId) {
+    throw new ContextCompileError("context.route_unresolved", "Context compiles only after a selected route.");
+  }
+  const budget = input.budget ?? DEFAULT_CONTEXT_BUDGET;
+  const selected = selectSections(input.sections, input.liveRevisions, input.request.forbiddenDomains ?? []);
+  const included: ContextCapsule["sections"] = [];
+  const overflow: ContextCapsule["overflow"] = [];
+  let bytes = 0;
+  let tokens = 0;
+  for (const section of selected) {
+    const hasText = typeof section.text === "string";
+    const hasBytes = typeof section.bytes === "number" && Number.isFinite(section.bytes) && section.bytes >= 0;
+    const hasTokens = typeof section.tokens === "number" && Number.isFinite(section.tokens) && section.tokens >= 0;
+    if (!hasText && !(hasBytes && hasTokens)) {
+      throw new ContextCompileError(
+        "context.unmeasured_section",
+        `Section "${section.sectionId}" has no text or trustworthy size measurements.`,
+      );
+    }
+    const text = section.text ?? "";
+    const sectionBytes = hasText ? Math.max(section.bytes ?? 0, measureBytes(text)) : section.bytes!;
+    const sectionTokens = hasText ? Math.max(section.tokens ?? 0, measureTokens(text)) : section.tokens!;
+    if (bytes + sectionBytes > budget.maxBytes || tokens + sectionTokens > budget.maxTokens) {
+      overflow.push({ sectionId: section.sectionId, bytes: sectionBytes, tokens: sectionTokens });
+      continue;
+    }
+    included.push({
+      sectionId: section.sectionId,
+      revision: section.revision,
+      path: section.path,
+      bytes: sectionBytes,
+      tokens: sectionTokens,
+    });
+    bytes += sectionBytes;
+    tokens += sectionTokens;
+  }
+  if (overflow.length > 0 && included.length === 0) {
+    throw new ContextCompileError("context.budget_overflow", "Context budget cannot hold any selected section.");
+  }
+  return {
+    routeId: input.request.id,
+    selectedId: input.decision.selectedId,
+    sections: included,
+    exclusions: overflow.map((item) => ({ sectionId: item.sectionId, reasonCode: "context.over_budget" })),
+    overflow,
+    bytes,
+    tokens,
+    sourceIds: included.map((section) => `${section.path}#${section.sectionId}@${section.revision}`),
+  };
+}
+
+export function capsuleBytes(capsule: ContextCapsule): string {
+  return `${JSON.stringify(capsule)}\n`;
+}

package/kernel/context/receipt.ts

@@ -0,0 +1,34 @@
+export interface ContextBudget {
+  maxBytes: number;
+  maxTokens: number;
+}
+
+export interface ContextExclusion {
+  sectionId: string;
+  reasonCode: string;
+}
+
+export interface ContextOverflow {
+  sectionId: string;
+  bytes: number;
+  tokens: number;
+}
+
+export interface ContextCapsule {
+  routeId: string;
+  selectedId: string;
+  sections: Array<{ sectionId: string; revision: string; path: string; bytes: number; tokens: number }>;
+  exclusions: ContextExclusion[];
+  overflow: ContextOverflow[];
+  bytes: number;
+  tokens: number;
+  sourceIds: string[];
+}
+
+export class ContextCompileError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}

package/kernel/context/selectors.ts

@@ -0,0 +1,30 @@
+import type { KnowledgeSection } from "../routing/types.js";
+import { ContextCompileError } from "./receipt.js";
+
+export function selectSections(
+  sections: readonly KnowledgeSection[],
+  liveRevisions: Record<string, string>,
+  forbiddenDomains: readonly string[] = [],
+): KnowledgeSection[] {
+  const selected: KnowledgeSection[] = [];
+  const seen = new Set<string>();
+  for (const section of [...sections].sort((left, right) => left.sectionId.localeCompare(right.sectionId))) {
+    if (!section.sectionId.trim()) {
+      throw new ContextCompileError("context.unresolved_section", "Context selector is missing a stable section ID.");
+    }
+    if (seen.has(section.sectionId)) continue;
+    seen.add(section.sectionId);
+    if (section.domain && forbiddenDomains.includes(section.domain)) {
+      throw new ContextCompileError("context.forbidden_domain", `Section ${section.sectionId} belongs to forbidden domain ${section.domain}.`);
+    }
+    const live = liveRevisions[section.sectionId];
+    if (!live) {
+      throw new ContextCompileError("context.unresolved_section", `Section ${section.sectionId} has no live revision.`);
+    }
+    if (live !== section.revision) {
+      throw new ContextCompileError("context.stale_revision", `Section ${section.sectionId} requested ${section.revision} but live revision is ${live}.`);
+    }
+    selected.push(section);
+  }
+  return selected;
+}

package/kernel/contribution/accepted-upstreams.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import type { ContributionManifest } from "../../contracts/contribution/contract.js";
+import { readPackageResourceFile } from "../composition/resources.js";
+import { githubIdentity } from "./github-metadata.js";
+import { loadUpstreams } from "./upstreams-load.js";
+import type { CheckIssue } from "./types.js";
+
+/** Promotion checks, not source discovery. Proposed work may retain explicit unknowns. */
+export function checkAcceptedUpstreams(manifest: ContributionManifest, targetRoot: string, skillRoot: string): CheckIssue[] {
+  const issues: CheckIssue[] = [];
+  const adopted = manifest.units.filter((unit) => unit.status === "accepted" && ["adapt", "reuse", "wrap", "vendor"].includes(unit.disposition));
+  if (!adopted.length) return issues;
+  const loaded = loadUpstreams(skillRoot);
+  const upstreams = new Map(loaded.upstreams.map((entry) => [entry.manifest.id, entry]));
+  for (const unit of adopted) {
+    const source = manifest.sources.find((entry) => entry.id === unit.upstream?.sourceId);
+    if (!source) continue; // The general checker reports unresolved sources.
+    const fail = (code: string, message: string): void => {
+      issues.push({ severity: "error", code: `contribution.${code}`, message, unitId: unit.id, sourceId: source.id });
+    };
+    const repository = source.canonicalUrl ? githubIdentity(source.canonicalUrl) : null;
+    if (!repository) {
+      if (source.kind === "repository" && !(manifest.synthetic && source.localPath && !source.canonicalUrl))
+        fail("upstream_identity_mismatch", "Accepted repository sources need a canonical supported repository identity; missing URLs do not waive provenance.");
+      continue; // Non-repository sources retain their own rights and provenance rules.
+    }
+    const upstream = source.upstreamId ? upstreams.get(source.upstreamId) : undefined;
+    if (!upstream) {
+      fail("upstream_required", "Accepting reusable repository material requires a catalog/upstreams identity.");
+      continue;
+    }
+    const identity = githubIdentity(upstream.manifest.canonicalUrl);
+    if (!identity || identity.owner.toLowerCase() !== repository.owner.toLowerCase() || identity.repo.toLowerCase() !== repository.repo.toLowerCase())
+      fail("upstream_identity_mismatch", "The reviewed source and upstream record identify different repositories.");
+    if (!source.registrySourceId || !upstream.manifest.sourceIds.includes(source.registrySourceId))
+      fail("upstream_source_mapping_missing", "The source must reference a source-registry entry owned by this upstream.");
+    const baselines = [upstream.manifest.baselines.reviewedSource, upstream.manifest.baselines.reviewedGuidance].filter(Boolean);
+    if (!source.revision || !/^[a-f0-9]{40}$/.test(source.revision) || !baselines.some((baseline) => baseline?.revision === source.revision))
+      fail(
+        "upstream_baseline_mismatch",
+        "Repository adoption requires an exact reviewed commit shared with the upstream record; tags and latest are not immutable evidence.",
+      );
+    if (!upstream.manifest.credits.acknowledge)
+      fail("upstream_credit_missing", "An accepted reusable contribution requires accurate acknowledgment of the project powering it.");
+    if (
+      unit.disposition === "adapt" &&
+      !manifest.derivations.some(
+        (entry) => entry.sourceIds.includes(source.id) && [unit.target.id, unit.target.path].includes(entry.target) && entry.baseline === source.revision,
+      )
+    )
+      fail("derivation_missing", "Accepted adapted guidance requires a source-to-target derivation at the reviewed baseline.");
+    if (source.rights.status !== "verified" || upstream.manifest.license.status !== "verified")
+      fail("upstream_rights_unverified", "Source and upstream rights must be verified before accepting reused material.");
+    // Retained license notices are source-specific for every adopted license, not only MIT.
+    if (upstream.manifest.license.noticeFile || upstream.manifest.license.spdx === "MIT") {
+      const notice = manifest.notices.find(
+        (entry) =>
+          entry.sourceId === source.id &&
+          entry.covers.some((covered) => [unit.id, unit.target.id, unit.target.path].some((target) => target === covered || target?.startsWith(`${covered}/`))),
+      );
+      if (!notice) {
+        fail("notice_missing", "Accepted material with a retained license notice needs that source's notice covering its target.");
+        continue;
+      }
+      try {
+        const bytes = readPackageResourceFile(targetRoot, notice.noticePath);
+        const digest = createHash("sha256").update(bytes).digest("hex");
+        if (
+          !upstream.notice ||
+          digest !== upstream.notice.sha256 ||
+          digest !== upstream.manifest.license.evidenceSha256 ||
+          digest !== source.rights.evidenceSha256 ||
+          notice.spdx !== upstream.manifest.license.spdx ||
+          notice.copyright !== upstream.manifest.copyright
+        )
+          fail("notice_mismatch", "Retained notice bytes and attribution must match the reviewed source and upstream license evidence.");
+      } catch {
+        fail("notice_unreadable", "The covering notice must be a readable, package-relative regular file without symlink traversal.");
+      }
+    }
+  }
+  return issues;
+}

package/kernel/contribution/adoption-map.ts

@@ -0,0 +1,153 @@
+import type { ContributionManifest } from "../../contracts/contribution/contract.js";
+
+/**
+ * ADOPTION_MAP.md: the human-readable projection of a contribution manifest. It is generated from
+ * the manifest only, so it never carries a claim the manifest does not. The only timestamp is
+ * the manifest's createdAt; the rest is deterministic for one manifest.
+ */
+function cell(value: string | number | boolean | undefined | null): string {
+  if (value === undefined || value === null || value === "") return "none";
+  return String(value).replace(/\|/gu, "\\|").replace(/\r?\n/gu, " ");
+}
+
+function table(header: string[], rows: string[][]): string[] {
+  if (!rows.length) return ["_none_"];
+  return [`| ${header.join(" | ")} |`, `| ${header.map(() => "---").join(" | ")} |`, ...rows.map((row) => `| ${row.map(cell).join(" | ")} |`)];
+}
+
+function bullets(items: readonly string[], empty = "_none_"): string[] {
+  return items.length ? items.map((item) => `- ${cell(item)}`) : [empty];
+}
+
+export function renderAdoptionMap(manifest: ContributionManifest): string {
+  const lines: string[] = [];
+  lines.push(`# Adoption map: ${manifest.id}`, "");
+  lines.push(`Goal: ${manifest.goal}`, "");
+  lines.push(`Created: ${manifest.createdAt}. Synthetic: ${manifest.synthetic ? "yes (labeled fixtures, not a creator's material)" : "no"}.`, "");
+  lines.push("## Routing", "");
+  lines.push(`- Scope: ${manifest.scope}`);
+  lines.push(`- Verdict: ${manifest.routing.verdict}`);
+  lines.push(`- Intended target: ${manifest.routing.intendedTarget}`);
+  lines.push(`- Effect: ${manifest.routing.effect}`);
+  lines.push(`- Reason: ${manifest.routing.reason}`, "");
+  lines.push("## Sources", "");
+  lines.push(
+    ...table(
+      ["id", "kind", "origin", "publisher", "revision", "retrieval", "rights", "refused directives"],
+      manifest.sources.map((source) => [
+        source.id,
+        source.kind,
+        source.canonicalUrl ?? source.localPath ?? "",
+        source.publisher ?? "",
+        source.revision ?? "unknown",
+        `${source.retrieval.status}${source.retrieval.notes ? ` (${source.retrieval.notes})` : ""}`,
+        `${source.rights.status}${source.rights.spdx ? ` ${source.rights.spdx}` : ""}${source.rights.evidence ? `; evidence ${source.rights.evidence}` : ""}`,
+        String(source.directives.length),
+      ]),
+    ),
+    "",
+  );
+  const refused = manifest.sources.flatMap((source) =>
+    source.directives.map((directive) => [source.id, directive.location, directive.category, directive.text]),
+  );
+  if (refused.length) {
+    lines.push(
+      "### Refused directives",
+      "",
+      "Sentences in the sources that read as instructions to an agent. They are recorded as data and were not followed.",
+      "",
+    );
+    lines.push(...table(["source", "location", "category", "text"], refused), "");
+  }
+  const unknowns = manifest.sources.flatMap((source) => source.unknowns.map((unknown) => `${source.id}: ${unknown}`));
+  if (unknowns.length) lines.push("### Source unknowns", "", ...bullets(unknowns), "");
+  lines.push("## Units", "");
+  lines.push(
+    ...table(
+      ["unit", "kind", "upstream location", "local target", "disposition", "status", "selection", "rationale", "verification"],
+      manifest.units.map((unit) => [
+        unit.id,
+        unit.kind,
+        unit.upstream ? `${unit.upstream.sourceId}${unit.upstream.selector ? ` ${unit.upstream.selector}` : ""}` : "original (no upstream)",
+        `${unit.target.kind}${unit.target.id ? ` ${unit.target.id}` : ""}${unit.target.path ? ` ${unit.target.path}` : ""}${unit.target.owner ? ` (owner ${unit.target.owner})` : ""}`,
+        unit.disposition,
+        unit.status,
+        unit.selection,
+        unit.rationale,
+        unit.verification.join("; "),
+      ]),
+    ),
+    "",
+  );
+  const applicability = manifest.units.flatMap((unit) => unit.applicability.map((claim) => `${unit.id}: ${claim}`));
+  if (applicability.length) lines.push("### Applicability claims to verify against a primary source", "", ...bullets(applicability), "");
+  lines.push("## Existing owners", "");
+  lines.push(
+    ...table(
+      ["id", "path", "match"],
+      manifest.existingOwners.map((owner) => [owner.id, owner.path, owner.match]),
+    ),
+    "",
+  );
+  lines.push("## Batch overlap", "");
+  lines.push(
+    ...table(
+      ["topic", "sources"],
+      manifest.batchOverlap.map((overlap) => [overlap.topic, overlap.sourceIds.join(", ")]),
+    ),
+    "",
+  );
+  lines.push("## Kept, changed, omitted, deferred", "");
+  for (const unit of manifest.units) {
+    lines.push(`### ${unit.id}`, "");
+    lines.push(`- Kept: ${unit.kept.length ? unit.kept.map(cell).join("; ") : "none"}`);
+    lines.push(`- Changed: ${unit.changed.length ? unit.changed.map(cell).join("; ") : "none"}`);
+    lines.push(`- Omitted: ${unit.omitted.length ? unit.omitted.map(cell).join("; ") : "none"}`);
+    lines.push(`- Deferred: ${unit.deferred.length ? unit.deferred.map(cell).join("; ") : "none"}`, "");
+  }
+  const conflicts = manifest.units.flatMap((unit) => unit.conflicts.map((conflict) => `${unit.id} with ${conflict.with}: ${conflict.resolution}`));
+  lines.push("## Conflicts", "", ...bullets(conflicts), "");
+  if (manifest.derivations.length) {
+    lines.push("## Derivations", "");
+    lines.push(
+      ...table(
+        ["target", "sources", "relationship", "notice", "reviewer", "reviewed"],
+        manifest.derivations.map((derivation) => [
+          derivation.target,
+          derivation.sourceIds.join(", "),
+          derivation.relationship,
+          derivation.notice ?? "",
+          derivation.reviewer,
+          derivation.reviewedAt,
+        ]),
+      ),
+      "",
+    );
+  }
+  if (manifest.notices.length) {
+    lines.push("## Notices", "");
+    lines.push(
+      ...table(
+        ["source", "license", "copyright", "notice path", "covers"],
+        manifest.notices.map((notice) => [notice.sourceId, notice.spdx, notice.copyright, notice.noticePath, notice.covers.join(", ")]),
+      ),
+      "",
+    );
+  }
+  if (manifest.evaluations.length) {
+    lines.push("## Evaluations", "");
+    lines.push(
+      ...table(
+        ["case", "unit", "kind", "description"],
+        manifest.evaluations.map((item) => [item.id, item.unitId, item.kind, item.description]),
+      ),
+      "",
+    );
+  }
+  lines.push("## Uncertainties", "", ...bullets(manifest.uncertainties), "");
+  lines.push("## Missing core mechanism", "");
+  lines.push(manifest.missingCoreMechanism.present ? `Present: ${manifest.missingCoreMechanism.description ?? "(no description)"}` : "None identified.", "");
+  lines.push("## Required checks", "", ...bullets(manifest.requiredChecks), "");
+  lines.push("## Affected outputs", "", ...bullets(manifest.affectedOutputs), "");
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/kernel/contribution/check.ts

@@ -0,0 +1,197 @@
+import { loadKnowledgePackages } from "../../catalog/knowledge-packages.js";
+import type { ContributionManifest, ContributionUnit, SourceRecord } from "../../contracts/contribution/contract.js";
+import { inferScope, readContributionManifest } from "./manifest-io.js";
+import type { CheckData, CheckIssue } from "./types.js";
+import { loadUpstreams } from "./upstreams-load.js";
+import { checkAcceptedUpstreams } from "./accepted-upstreams.js";
+
+/**
+ * `contribution.check`: validate a contribution root. Schema, scope routing, rights evidence for
+ * adapted or copied units, notices for copied material, refused directives, original units
+ * without a fabricated upstream, existing owners, and evaluation coverage. Errors block; warnings
+ * are review prompts. Nothing here changes a file.
+ */
+const COPYING_DISPOSITIONS = new Set<ContributionUnit["disposition"]>(["reuse", "wrap", "vendor"]);
+const RIGHTS_DISPOSITIONS = new Set<ContributionUnit["disposition"]>(["adapt", "reuse", "wrap", "vendor"]);
+const INCOMPLETE_RETRIEVAL = new Set(["excerpt", "screenshot", "secondary", "inaccessible", "not-retrieved"]);
+const AESTHETIC = /\b(?:style|aesthetic|palette|typography|typeface|colou?r scheme)\b/iu;
+const STALE_DAYS = 180;
+
+function unitTargets(unit: ContributionUnit): string[] {
+  return [unit.id, unit.target.id, unit.target.path].filter((value): value is string => Boolean(value));
+}
+
+const normalizePath = (value: string): string => value.replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
+
+/** A notices[].covers entry covers a candidate when it names it exactly or names a parent directory of it. */
+function coversCandidate(covered: string, candidate: string): boolean {
+  if (covered === candidate) return true;
+  const coveredPath = normalizePath(covered);
+  const candidatePath = normalizePath(candidate);
+  return coveredPath !== "" && (candidatePath === coveredPath || candidatePath.startsWith(`${coveredPath}/`));
+}
+
+function noticeCovers(manifest: ContributionManifest, candidates: readonly string[], sourceId: string): boolean {
+  return manifest.notices.some(
+    (notice) => notice.sourceId === sourceId && notice.covers.some((covered) => candidates.some((candidate) => coversCandidate(covered, candidate))),
+  );
+}
+
+/**
+ * An upgrade plan (`b2c contribute upgrade-plan`) records its upstream as a source with retrieval
+ * `excerpt`: release metadata and the license digest from the recorded observation, never the
+ * whole repository. That source's review belongs to its manifest under catalog/upstreams, so the
+ * complete-source rule for adaptation does not apply to it. Every other source keeps the rule.
+ */
+function ownedByUpstreamManifest(source: SourceRecord, upstreamIds: ReadonlySet<string>): boolean {
+  return source.upstreamId !== undefined && upstreamIds.has(source.upstreamId);
+}
+
+export function checkContribution(targetRoot: string, deps: { skillRoot: string; now: () => Date }): CheckData {
+  const manifest = readContributionManifest(targetRoot);
+  const upstreamIds = new Set(
+    manifest.sources.some((source) => source.upstreamId) ? loadUpstreams(deps.skillRoot).upstreams.map((entry) => entry.manifest.id) : [],
+  );
+  const issues: CheckIssue[] = [];
+  const error = (code: string, message: string, ids: { unitId?: string; sourceId?: string } = {}): void => {
+    issues.push({ severity: "error", code, message, ...ids });
+  };
+  const warning = (code: string, message: string, ids: { unitId?: string; sourceId?: string } = {}): void => {
+    issues.push({ severity: "warning", code, message, ...ids });
+  };
+  const packages = loadKnowledgePackages(deps.skillRoot);
+  const packageIds = new Set<string>(packages.map((pkg) => pkg.id));
+  const packageTitles = new Map(packages.map((pkg) => [pkg.title.toLowerCase(), pkg.id]));
+  const sources = new Map(manifest.sources.map((source) => [source.id, source]));
+  const unitIds = new Set(manifest.units.map((unit) => unit.id));
+
+  const inferred = inferScope(manifest.goal, manifest.units);
+  if (manifest.routing.verdict !== manifest.scope)
+    error("contribution.scope_mismatch", `routing.verdict ${manifest.routing.verdict} differs from scope ${manifest.scope}.`);
+  if (manifest.scope !== "maintenance" && inferred.verdict === "maintenance")
+    error("contribution.scope_mismatch", `scope ${manifest.scope} cannot change maintainer-owned paths: ${inferred.maintenanceTargets.join(", ")}.`);
+  if (manifest.scope === "maintenance" && inferred.verdict !== "maintenance")
+    warning("contribution.scope_broader_than_targets", "scope maintenance declared, but no unit targets a maintainer-owned path.");
+
+  for (const source of manifest.sources) {
+    if (source.retrievedAt) {
+      const ageDays = (deps.now().getTime() - new Date(source.retrievedAt).getTime()) / 86_400_000;
+      if (ageDays > STALE_DAYS)
+        warning("contribution.source_stale", `${source.id} was retrieved ${Math.floor(ageDays)} days ago; re-read it before promotion.`, {
+          sourceId: source.id,
+        });
+    }
+  }
+
+  for (const unit of manifest.units) {
+    const ids = { unitId: unit.id };
+    if (unit.upstream === null && unit.disposition !== "original") {
+      error(
+        "contribution.original_disposition_mismatch",
+        `${unit.id} has no upstream but disposition ${unit.disposition}; only original units omit an upstream.`,
+        ids,
+      );
+    }
+    if (unit.upstream !== null && unit.disposition === "original") {
+      error("contribution.fabricated_originality", `${unit.id} names upstream ${unit.upstream.sourceId} but claims disposition original.`, ids);
+    }
+    const source = unit.upstream ? sources.get(unit.upstream.sourceId) : undefined;
+    if (unit.upstream && !source)
+      error("contribution.source_unknown", `${unit.id} names upstream ${unit.upstream.sourceId}, which is not a source in this manifest.`, ids);
+    if (source && RIGHTS_DISPOSITIONS.has(unit.disposition) && source.rights.status !== "verified") {
+      const soft = unit.status !== "accepted" && unit.disposition === "adapt" && source.rights.status === "unverified" && unit.kind === "knowledge";
+      const message = `${unit.id} is ${unit.disposition} but source ${source.id} rights are ${source.rights.status}.`;
+      if (soft) warning("contribution.rights_unverified", `${message} Read the license text before promotion.`, { ...ids, sourceId: source.id });
+      else error("contribution.rights_unverified", message, { ...ids, sourceId: source.id });
+    }
+    if (source && unit.disposition === "adapt" && INCOMPLETE_RETRIEVAL.has(source.retrieval.status) && !ownedByUpstreamManifest(source, upstreamIds)) {
+      error(
+        "contribution.incomplete_source_for_adaptation",
+        `${unit.id} adapts source ${source.id}, whose retrieval is ${source.retrieval.status}; adapt needs the complete source.`,
+        { ...ids, sourceId: source.id },
+      );
+    }
+    if (COPYING_DISPOSITIONS.has(unit.disposition) && !noticeCovers(manifest, unitTargets(unit), unit.upstream?.sourceId ?? "")) {
+      error(
+        "contribution.notice_missing",
+        `${unit.id} copies material (${unit.disposition}) but no notices[] entry covers ${unit.target.id ?? unit.target.path ?? unit.id}.`,
+        ids,
+      );
+    }
+    if (unit.target.kind === "existing-reference") {
+      if (!unit.target.id || !packageIds.has(unit.target.id))
+        error(
+          "contribution.owner_unknown",
+          `${unit.id} targets existing reference ${unit.target.id ?? "(none)"}, which is not a loaded knowledge package.`,
+          ids,
+        );
+    }
+    if (unit.target.kind === "new-reference") {
+      const duplicate = packageTitles.get(unit.title.toLowerCase());
+      if (duplicate)
+        warning("contribution.duplicate_reference_candidate", `${unit.id} proposes a new reference titled like existing package ${duplicate}.`, ids);
+    }
+    if (unit.kind === "knowledge" && unit.selection === "always" && AESTHETIC.test(unit.rationale)) {
+      error(
+        "contribution.aesthetic_universal_default",
+        `${unit.id} would make an aesthetic preference an automatic default; a creator's style stays a selectable method.`,
+        ids,
+      );
+    }
+    const cases = manifest.evaluations.filter((item) => item.unitId === unit.id);
+    if (
+      unit.kind === "knowledge" &&
+      unit.disposition === "adapt" &&
+      !cases.some((item) => item.kind === "counterexample" || item.kind === "launchbench-scenario")
+    ) {
+      error("contribution.evaluation_missing", `${unit.id} adapts knowledge without a counterexample or launchbench-scenario evaluation.`, ids);
+    }
+    if (
+      unit.kind === "implementation" &&
+      (unit.disposition === "reuse" || unit.disposition === "wrap") &&
+      !cases.some((item) => item.kind === "command" || item.kind === "comparison")
+    ) {
+      warning("contribution.evaluation_recommended", `${unit.id} reuses an implementation without a command or comparison evaluation.`, ids);
+    }
+  }
+
+  for (const derivation of manifest.derivations) {
+    if (
+      derivation.relationship === "copied" &&
+      !derivation.notice &&
+      !derivation.sourceIds.every((sourceId) => noticeCovers(manifest, [derivation.target], sourceId))
+    ) {
+      error("contribution.notice_missing", `derivation for ${derivation.target} copies material without a notice.`);
+    }
+    for (const sourceId of derivation.sourceIds) {
+      if (!sources.has(sourceId)) error("contribution.source_unknown", `derivation for ${derivation.target} names unknown source ${sourceId}.`, { sourceId });
+    }
+  }
+  for (const evaluation of manifest.evaluations) {
+    if (!unitIds.has(evaluation.unitId)) error("contribution.evaluation_unit_unknown", `evaluation ${evaluation.id} names unknown unit ${evaluation.unitId}.`);
+  }
+  for (const notice of manifest.notices) {
+    if (!sources.has(notice.sourceId))
+      error("contribution.source_unknown", `notice ${notice.noticePath} names unknown source ${notice.sourceId}.`, { sourceId: notice.sourceId });
+  }
+
+  issues.push(...checkAcceptedUpstreams(manifest, targetRoot, deps.skillRoot));
+
+  const refusedDirectives = manifest.sources.reduce((sum, source) => sum + source.directives.length, 0);
+  return {
+    target: targetRoot,
+    manifestId: manifest.id,
+    pass: !issues.some((issue) => issue.severity === "error"),
+    issues,
+    summary: {
+      units: manifest.units.length,
+      sources: manifest.sources.length,
+      rightsVerified: manifest.sources.filter((source) => source.rights.status === "verified").length,
+      rightsUnknown: manifest.sources.filter((source) => source.rights.status === "unknown").length,
+      copiedUnits: manifest.units.filter((unit) => COPYING_DISPOSITIONS.has(unit.disposition)).length,
+      originalUnits: manifest.units.filter((unit) => unit.upstream === null).length,
+      refusedDirectives,
+      evaluations: manifest.evaluations.length,
+    },
+  };
+}