@danypops/papyrus 0.11.4 → 0.13.0

package/src/domain-services.ts

@@ -1,12 +1,56 @@
+import {
+	ARTIFACT_SCOPE_MAX_ARTIFACTS,
+	RULE_TEXT_HARD_LIMIT_CHARACTERS,
+	SKILL_INVOCATION_MAX_CALL_DEPTH,
+	SKILL_INVOCATION_MAX_LINKED_ARTIFACTS,
+} from "./constants.ts";
 import type { Artifact, CreateArtifactInput } from "./domain/artifact.ts";
+import type { ArtifactEventContext } from "./domain/artifact-event.ts";
+import { normalizeProjectRoot } from "./domain/task-scope.ts";
 import { validateSkillDefinition } from "./domain/skill-definition.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
+import type { ArtifactScopeStore } from "./ports/artifact-scope-store.ts";
 import { NOTE_SUBTYPE } from "./note-service.ts";
+import type { AuthorityRegistry } from "./authority-registry.ts";
 
 export interface ListFilter {
 	status?: string;
 	text?: string;
 	limit?: number;
+	/** When supplied, results are limited to artifacts scoped to this project (or the unscoped bucket, for an empty string is not accepted -- use assignArtifactProject's own validation). */
+	projectRoot?: string;
+}
+
+/**
+ * Shared by listDocuments/listRules/listSkills: when filter.projectRoot is given, resolve
+ * via ArtifactScopeStore first and post-filter by kind/status/text (mirrors Tasks.list's
+ * established scoped-listing shape); otherwise fall back to the existing unscoped query
+ * path unchanged, so every caller that predates project scoping keeps working exactly as
+ * before.
+ */
+function listScoped(artifacts: ArtifactStore, scopes: ArtifactScopeStore, kind: string, filter: ListFilter, excludeSubtype?: string): Artifact[] {
+	if (filter.projectRoot === undefined) return artifacts.query({ kind, excludeSubtype, status: filter.status, text: filter.text, limit: filter.limit });
+	const limit = filter.limit ?? ARTIFACT_SCOPE_MAX_ARTIFACTS;
+	if (!Number.isInteger(limit) || limit < 1 || limit > ARTIFACT_SCOPE_MAX_ARTIFACTS) {
+		throw new Error(`list limit must be between 1 and ${ARTIFACT_SCOPE_MAX_ARTIFACTS}`);
+	}
+	const projectRoot = normalizeProjectRoot(filter.projectRoot);
+	const ids = scopes.ids(projectRoot, ARTIFACT_SCOPE_MAX_ARTIFACTS);
+	const text = filter.text?.toLowerCase();
+	return ids
+		.map((id) => artifacts.get(id))
+		.filter((artifact): artifact is Artifact => artifact?.kind === kind && artifact.subtype !== excludeSubtype)
+		.filter((artifact) => filter.status === undefined || artifact.status === filter.status)
+		.filter((artifact) => text === undefined || artifact.title.toLowerCase().includes(text) || artifact.body.toLowerCase().includes(text))
+		.sort((left, right) => right.updated_at.localeCompare(left.updated_at) || left.id.localeCompare(right.id))
+		.slice(0, limit);
+}
+
+/** Shared by assignDocumentProject/assignRuleProject/assignSkillProject. */
+function assignArtifactProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, kind: string, projectRoot: string | undefined): Artifact {
+	requireKind(artifacts, id, kind);
+	scopes.assign(id, projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot), projectRoot === undefined ? "unscoped" : "explicit");
+	return artifacts.get(id)!;
 }
 
 function requireKind(artifacts: ArtifactStore, id: string, kind: string): Artifact {
@@ -25,10 +69,25 @@ function rejectsNoteTemplate(artifacts: ArtifactStore, templateId: string | unde
 		&& (defaults as Record<string, unknown>)["subtype"] === NOTE_SUBTYPE;
 }
 
-function requireNotesFacade(): never {
+/** caller never owns NOTE_SUBTYPE, so requireArtifactAllowed always throws — the trailing throw only satisfies TypeScript's control-flow analysis for a `never`-returning function. */
+function requireNotesFacade(authority: AuthorityRegistry, caller: string): never {
+	authority.requireArtifactAllowed("doc", NOTE_SUBTYPE, "create", caller);
 	throw new Error("note creation requires notes.capture");
 }
 
+function templateSubtype(artifacts: ArtifactStore, templateId: string | undefined): string | undefined {
+	if (!templateId) return undefined;
+	const defaults = artifacts.get(templateId)?.extra["defaults"];
+	if (typeof defaults !== "object" || defaults === null || Array.isArray(defaults)) return undefined;
+	const subtype = (defaults as Record<string, unknown>)["subtype"];
+	return typeof subtype === "string" ? subtype : undefined;
+}
+
+function requireMutableDocument(document: Artifact, authority: AuthorityRegistry): Artifact {
+	authority.requireArtifactAllowed(document.kind, document.subtype, "status", "docs");
+	return document;
+}
+
 export interface CreateDocumentInput {
 	title: string;
 	body?: string;
@@ -36,6 +95,8 @@ export interface CreateDocumentInput {
 	labels?: string[];
 	extra?: Record<string, unknown>;
 	templateId?: string;
+	/** Optional at creation, unlike Tasks -- omitting it leaves the Doc in the unscoped bucket, matching today's default behavior for every existing caller. */
+	projectRoot?: string;
 }
 
 export type DocumentTransition = "activate" | "archive" | "reopen";
@@ -47,21 +108,35 @@ const DOCUMENT_TRANSITIONS: Record<DocumentTransition, { from: string[]; to: str
 	reopen: { from: ["archived"], to: "draft" },
 };
 
-export function createDocument(artifacts: ArtifactStore, input: CreateDocumentInput): Artifact {
-	if (rejectsNoteTemplate(artifacts, input.templateId, input.subtype)) requireNotesFacade();
-	return artifacts.create({
+export function createDocument(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateDocumentInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	if (rejectsNoteTemplate(artifacts, input.templateId, input.subtype)) requireNotesFacade(authority, "docs");
+	authority.requireArtifactAllowed("doc", input.subtype ?? templateSubtype(artifacts, input.templateId), "create", "docs");
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const document = artifacts.create({
 		kind: "doc",
+		// Explicit, not defaultStatusFor's "first status row by rowid" fallback -- the same
+		// heuristic that made Task creation non-deterministic on a migrated database. Every
+		// creation path that has no caller-supplied initial status must set one explicitly.
+		status: "draft",
 		title: input.title,
 		body: input.body,
 		subtype: input.subtype,
 		labels: input.labels,
 		extra: input.extra,
 		templateId: input.templateId,
-	});
+	}, context);
+	scopes.assign(document.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return document;
 }
 
-export function listDocuments(artifacts: ArtifactStore, filter: ListFilter): Artifact[] {
-	return artifacts.query({ kind: "doc", excludeSubtype: NOTE_SUBTYPE, ...filter });
+export function listDocuments(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "doc", filter, NOTE_SUBTYPE);
+}
+
+export function assignDocumentProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, projectRoot: string | undefined): Artifact {
+	requireDocument(artifacts, id); // rejects Notes -- project reassignment for notes goes through notes.* like everything else about them
+	scopes.assign(id, projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot), projectRoot === undefined ? "unscoped" : "explicit");
+	return artifacts.get(id)!;
 }
 
 function requireDocument(artifacts: ArtifactStore, id: string): Artifact {
@@ -75,17 +150,19 @@ export function showDocument(artifacts: ArtifactStore, id: string): Artifact {
 	return artifacts.get(id, { tree: true })!;
 }
 
-export function transitionDocument(artifacts: ArtifactStore, id: string, action: DocumentTransition): Artifact {
-	const document = requireDocument(artifacts, id);
+export function transitionDocument(artifacts: ArtifactStore, id: string, action: DocumentTransition, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	const document = requireMutableDocument(requireDocument(artifacts, id), authority);
 	const transition = DOCUMENT_TRANSITIONS[action];
 	if (!transition.from.includes(document.status)) throw new Error(`cannot ${action} document from ${document.status}`);
-	return artifacts.setStatus(id, transition.to)!;
+	return artifacts.setStatus(id, transition.to, context)!;
 }
 
-export function linkDocument(artifacts: ArtifactStore, id: string, relation: DocumentRelation, targetId: string): Artifact {
-	requireDocument(artifacts, id);
-	if (!artifacts.get(targetId)) throw new Error(`target artifact "${targetId}" not found`);
-	artifacts.link({ from: id, relation, to: targetId });
+export function linkDocument(artifacts: ArtifactStore, id: string, relation: DocumentRelation, targetId: string, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	requireMutableDocument(requireDocument(artifacts, id), authority);
+	const target = artifacts.get(targetId);
+	if (!target) throw new Error(`target artifact "${targetId}" not found`);
+	requireMutableDocument(target, authority);
+	artifacts.link({ from: id, relation, to: targetId }, context);
 	return showDocument(artifacts, id);
 }
 
@@ -97,13 +174,36 @@ export interface CreateRuleInput {
 	severity?: "block" | "warn" | "info";
 	labels?: string[];
 	extra?: Record<string, unknown>;
+	projectRoot?: string;
 }
 
 export type RuleTransition = "enable" | "disable";
 
-export function createRule(artifacts: ArtifactStore, input: CreateRuleInput): Artifact {
-	return artifacts.create({
+/**
+ * A Rule's condition+action+body is injected into every relevant turn for the rule's entire
+ * lifetime -- a permanent tax on every future turn's context budget, not a one-time cost.
+ * Rejects (rather than silently truncating or merely warning) once a rule is unambiguously
+ * bloated, since a silently-truncated rule would inject different text than what its author
+ * reviewed, and a warning nobody reads is not a bound. See RULE_TEXT_HARD_LIMIT_CHARACTERS's
+ * own comment in constants.ts for the research this threshold is grounded in.
+ */
+function assertRuleTextWithinBounds(condition: string | undefined, action: string | undefined, body: string | undefined): void {
+	const combined = (condition ?? "").length + (action ?? "").length + (body ?? "").length;
+	if (combined > RULE_TEXT_HARD_LIMIT_CHARACTERS) {
+		throw new Error(
+			`rule condition+action+body is ${combined} characters, exceeding the ${RULE_TEXT_HARD_LIMIT_CHARACTERS}-character bound. ` +
+				"A Rule is injected into every relevant turn for its entire lifetime -- this is a permanent context-budget tax, not a one-time cost. " +
+				"Split it: keep a short Rule (the condition and the invariant itself), and move the full reasoning, examples, and research into a linked Doc.",
+		);
+	}
+}
+
+export function createRule(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateRuleInput, context?: ArtifactEventContext): Artifact {
+	assertRuleTextWithinBounds(input.condition, input.action, input.body);
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const rule = artifacts.create({
 		kind: "rule",
+		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
 		title: input.title,
 		body: input.body,
 		labels: input.labels,
@@ -113,11 +213,17 @@ export function createRule(artifacts: ArtifactStore, input: CreateRuleInput): Ar
 			...(input.action ? { action: input.action } : {}),
 			severity: input.severity ?? "info",
 		},
-	});
+	}, context);
+	scopes.assign(rule.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return rule;
+}
+
+export function listRules(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "rule", filter);
 }
 
-export function listRules(artifacts: ArtifactStore, filter: ListFilter): Artifact[] {
-	return artifacts.query({ kind: "rule", ...filter });
+export function assignRuleProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, projectRoot: string | undefined): Artifact {
+	return assignArtifactProject(artifacts, scopes, id, "rule", projectRoot);
 }
 
 /** Global rules always apply; scoped workflow rules apply only while their run owns active focus. */
@@ -144,18 +250,18 @@ export function previewRule(artifacts: ArtifactStore, id: string): string {
 	return `• ${rule.title}${condition}\n  ${action}`;
 }
 
-export function transitionRule(artifacts: ArtifactStore, id: string, action: RuleTransition): Artifact {
+export function transitionRule(artifacts: ArtifactStore, id: string, action: RuleTransition, context?: ArtifactEventContext): Artifact {
 	const rule = requireKind(artifacts, id, "rule");
 	const expected = action === "enable" ? "deprecated" : "active";
 	const target = action === "enable" ? "active" : "deprecated";
 	if (rule.status !== expected) throw new Error(`cannot ${action} rule from ${rule.status}`);
-	return artifacts.setStatus(id, target)!;
+	return artifacts.setStatus(id, target, context)!;
 }
 
-export function gateTaskWithRule(artifacts: ArtifactStore, ruleId: string, taskId: string): Artifact {
+export function gateTaskWithRule(artifacts: ArtifactStore, ruleId: string, taskId: string, context?: ArtifactEventContext): Artifact {
 	requireKind(artifacts, ruleId, "rule");
 	requireKind(artifacts, taskId, "task");
-	artifacts.link({ from: ruleId, relation: "gates", to: taskId });
+	artifacts.link({ from: ruleId, relation: "gates", to: taskId }, context);
 	return showRule(artifacts, ruleId);
 }
 
@@ -168,6 +274,7 @@ export interface CreateSkillInput {
 	definition?: unknown;
 	labels?: string[];
 	extra?: Record<string, unknown>;
+	projectRoot?: string;
 }
 
 export interface CreateArtifactTemplateInput {
@@ -177,18 +284,21 @@ export interface CreateArtifactTemplateInput {
 	required?: string[];
 	body?: string;
 	labels?: string[];
+	projectRoot?: string;
 }
 
 export type SkillTransition = "enable" | "disable";
 
-export function createSkill(artifacts: ArtifactStore, input: CreateSkillInput): Artifact {
+export function createSkill(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateSkillInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
 	if (input.definition !== undefined && (input.trigger !== undefined || input.steps !== undefined || input.tools !== undefined)) {
 		throw new Error("workflow Skill definition cannot be mixed with legacy trigger, steps, or tools");
 	}
 	const definition = input.definition === undefined ? undefined : validateSkillDefinition(input.definition);
-	if (definition?.blueprints.docs.some((document) => document.subtype === NOTE_SUBTYPE)) requireNotesFacade();
-	return artifacts.create({
+	if (definition?.blueprints.docs.some((document) => document.subtype === NOTE_SUBTYPE)) requireNotesFacade(authority, "skills");
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const skill = artifacts.create({
 		kind: "skill",
+		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
 		subtype: definition ? "workflow" : undefined,
 		title: input.title,
 		body: input.body,
@@ -200,13 +310,17 @@ export function createSkill(artifacts: ArtifactStore, input: CreateSkillInput):
 			...(input.steps ? { steps: input.steps } : {}),
 			...(input.tools ? { tools: input.tools } : {}),
 		},
-	});
+	}, context);
+	scopes.assign(skill.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return skill;
 }
 
-export function createArtifactTemplate(artifacts: ArtifactStore, input: CreateArtifactTemplateInput): Artifact {
-	if (input.targetKind === "doc" && input.defaults?.["subtype"] === NOTE_SUBTYPE) requireNotesFacade();
-	return artifacts.create({
+export function createArtifactTemplate(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateArtifactTemplateInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	if (input.targetKind === "doc" && input.defaults?.["subtype"] === NOTE_SUBTYPE) requireNotesFacade(authority, "skills");
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const template = artifacts.create({
 		kind: "skill",
+		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
 		subtype: "artifact-template",
 		title: input.title,
 		body: input.body,
@@ -216,16 +330,22 @@ export function createArtifactTemplate(artifacts: ArtifactStore, input: CreateAr
 			defaults: input.defaults ?? {},
 			required: input.required ?? ["title"],
 		},
-	});
+	}, context);
+	scopes.assign(template.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return template;
 }
 
-export function instantiateTemplate(artifacts: ArtifactStore, templateId: string, input: CreateArtifactInput): Artifact {
-	if (rejectsNoteTemplate(artifacts, templateId, input.subtype)) requireNotesFacade();
-	return artifacts.create({ ...input, templateId });
+export function instantiateTemplate(artifacts: ArtifactStore, templateId: string, input: CreateArtifactInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
+	if (rejectsNoteTemplate(artifacts, templateId, input.subtype)) requireNotesFacade(authority, "skills");
+	return artifacts.create({ ...input, templateId }, context);
 }
 
-export function listSkills(artifacts: ArtifactStore, filter: ListFilter): Artifact[] {
-	return artifacts.query({ kind: "skill", ...filter });
+export function listSkills(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "skill", filter);
+}
+
+export function assignSkillProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, projectRoot: string | undefined): Artifact {
+	return assignArtifactProject(artifacts, scopes, id, "skill", projectRoot);
 }
 
 export function showSkill(artifacts: ArtifactStore, id: string): Artifact {
@@ -233,8 +353,7 @@ export function showSkill(artifacts: ArtifactStore, id: string): Artifact {
 	return artifacts.get(id, { tree: true })!;
 }
 
-export function skillInvocation(artifacts: ArtifactStore, id: string): string {
-	const skill = requireKind(artifacts, id, "skill");
+function skillInvocationBody(skill: Artifact): string {
 	if (skill.subtype === "artifact-template") {
 		return `Create an artifact using Papyrus template "${skill.title}".\ntemplate_id: ${skill.id}\nAsk for or infer all required template fields, then call the skills domain tool instantiate action.`;
 	}
@@ -261,10 +380,52 @@ export function skillInvocation(artifacts: ArtifactStore, id: string): string {
 	].join("\n");
 }
 
-export function transitionSkill(artifacts: ArtifactStore, id: string, action: SkillTransition): Artifact {
+/**
+ * Skills are special: invoking one queries Papyrus for the skill's real outgoing graph edges
+ * -- not just its own static body/extra fields -- so a Skill linked to existing Tasks, Rules,
+ * or Docs surfaces that linked context on invocation. A Skill can also link to and invoke
+ * OTHER Skills (any relation whose target is itself a Skill, e.g. the same "triggers" relation
+ * workflow execution already uses for skill-to-task edges): invoking the parent recursively
+ * composes the linked skill's own invocation. Bounded and cycle-safe -- a skill-calls-skill
+ * edge cycle degrades to a marker instead of infinite-looping, matching the cycle-safety
+ * discipline already established for ConversationJournal reply chains and task dependency
+ * graphs. `visited` and `depth` are recursion-internal; callers should not pass them.
+ */
+export function skillInvocation(artifacts: ArtifactStore, id: string, visited: Set<string> = new Set(), depth = 0): string {
+	const skill = requireKind(artifacts, id, "skill");
+	visited.add(id);
+	const sections = [skillInvocationBody(skill)];
+
+	const edges = artifacts.relationships({ artifactIds: [id] }).filter((edge) => edge.from === id).slice(0, SKILL_INVOCATION_MAX_LINKED_ARTIFACTS);
+	const linkedArtifactLines: string[] = [];
+	const linkedSkillSections: string[] = [];
+	for (const edge of edges) {
+		const target = artifacts.get(edge.to);
+		if (!target) continue; // dangling edge -- defensive, should not happen
+		if (target.kind !== "skill") {
+			linkedArtifactLines.push(`- ${edge.relation} ${target.kind} "${target.title}" (${target.id})`);
+			continue;
+		}
+		if (visited.has(target.id)) {
+			linkedSkillSections.push(`Also linked via ${edge.relation} to skill "${target.title}" (${target.id}) -- already invoked above in this chain, not repeated.`);
+		} else if (depth + 1 > SKILL_INVOCATION_MAX_CALL_DEPTH) {
+			linkedSkillSections.push(`Also linked via ${edge.relation} to skill "${target.title}" (${target.id}) -- call depth limit reached, invoke it separately.`);
+		} else {
+			const nested = skillInvocation(artifacts, target.id, visited, depth + 1);
+			linkedSkillSections.push(`Also invoke linked skill (${edge.relation}) "${target.title}" (${target.id}):\n${nested}`);
+		}
+	}
+	if (linkedArtifactLines.length > 0) {
+		sections.push(["Linked context (query Papyrus for full detail before proceeding):", ...linkedArtifactLines].join("\n"));
+	}
+	for (const section of linkedSkillSections) sections.push(section);
+	return sections.join("\n\n");
+}
+
+export function transitionSkill(artifacts: ArtifactStore, id: string, action: SkillTransition, context?: ArtifactEventContext): Artifact {
 	const skill = requireKind(artifacts, id, "skill");
 	const expected = action === "enable" ? "deprecated" : "active";
 	const target = action === "enable" ? "active" : "deprecated";
 	if (skill.status !== expected) throw new Error(`cannot ${action} skill from ${skill.status}`);
-	return artifacts.setStatus(id, target)!;
+	return artifacts.setStatus(id, target, context)!;
 }

package/src/graph-projection-service.ts

@@ -0,0 +1,103 @@
+/**
+ * graph-projection-service.ts — the generic graph projection protocol for external bounded
+ * contexts. See src/domain/graph-projection.ts for the batch/checkpoint shapes and the
+ * documented, deliberate scope limits of this first walking-skeleton slice.
+ */
+import { GRAPH_PROJECTION_ID_MAX_LENGTH, GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH, GRAPH_PROJECTION_MAX_EDGES_PER_BATCH } from "./constants.ts";
+import { GRAPH_PROJECTION_SCHEMA_VERSION, type GraphProjectionBatch, type GraphProjectionResult } from "./domain/graph-projection.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
+import type { GraphProjectionStore } from "./ports/graph-projection-store.ts";
+import type { AuthorityRegistry } from "./authority-registry.ts";
+
+function boundedId(value: string, label: string): string {
+	if (!value || value.length === 0) throw new Error(`${label} is required`);
+	if (value.length > GRAPH_PROJECTION_ID_MAX_LENGTH) throw new Error(`${label} exceeds ${GRAPH_PROJECTION_ID_MAX_LENGTH} characters`);
+	return value;
+}
+
+export class GraphProjection {
+	constructor(
+		private readonly artifacts: ArtifactStore,
+		private readonly store: GraphProjectionStore,
+		private readonly authority: AuthorityRegistry,
+	) {}
+
+	checkpoint(producerId: string) {
+		return this.store.getCheckpoint(boundedId(producerId, "producer_id"));
+	}
+
+	apply(batch: GraphProjectionBatch): GraphProjectionResult {
+		if (batch.schemaVersion !== GRAPH_PROJECTION_SCHEMA_VERSION) {
+			throw new Error(`unsupported graph projection schema version "${batch.schemaVersion}", expected "${GRAPH_PROJECTION_SCHEMA_VERSION}"`);
+		}
+		const producerId = boundedId(batch.producerId, "producer_id");
+		const batchId = boundedId(batch.batchId, "batch_id");
+		if (!Number.isInteger(batch.sequence) || batch.sequence < 1) throw new Error("sequence must be a positive integer");
+		if (batch.artifacts.length > GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH) {
+			throw new Error(`batch is bounded to ${GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH} artifacts; got ${batch.artifacts.length}`);
+		}
+		if (batch.edges.length > GRAPH_PROJECTION_MAX_EDGES_PER_BATCH) {
+			throw new Error(`batch is bounded to ${GRAPH_PROJECTION_MAX_EDGES_PER_BATCH} edges; got ${batch.edges.length}`);
+		}
+		for (const artifact of batch.artifacts) boundedId(artifact.externalId, "artifact externalId");
+		for (const edge of batch.edges) { boundedId(edge.from, "edge from"); boundedId(edge.to, "edge to"); }
+
+		const existingCheckpoint = this.store.getCheckpoint(producerId);
+		if (existingCheckpoint?.lastBatchId === batchId && existingCheckpoint.lastSequence === batch.sequence) {
+			return { producerId, batchId, sequence: batch.sequence, artifactsUpserted: 0, artifactsCreated: 0, edgesUpserted: 0, alreadyApplied: true };
+		}
+		if (existingCheckpoint === null) {
+			if (batch.sequence !== 1) throw new Error(`first batch for producer "${producerId}" must have sequence 1, got ${batch.sequence}`);
+		} else {
+			if (batch.sequence <= existingCheckpoint.lastSequence) {
+				throw new Error(`stale batch: sequence ${batch.sequence} is not after checkpoint sequence ${existingCheckpoint.lastSequence} for producer "${producerId}"`);
+			}
+			if (batch.sequence > existingCheckpoint.lastSequence + 1) {
+				throw new Error(`sequence gap for producer "${producerId}": expected ${existingCheckpoint.lastSequence + 1}, got ${batch.sequence}`);
+			}
+		}
+
+		// Authority up front, before any write: a producer that doesn't own a subtype/relation
+		// it's trying to project into must fail closed, not partially apply then fail midway.
+		for (const artifact of batch.artifacts) this.authority.requireArtifactAllowed(artifact.kind, artifact.subtype, "create", producerId);
+		for (const edge of batch.edges) this.authority.requireRelationAllowed(edge.relation, "link", producerId);
+
+		const atomic = requireAtomicArtifactStore(this.artifacts);
+		let artifactsCreated = 0;
+		let artifactsUpserted = 0;
+		let edgesUpserted = 0;
+		atomic.atomic(() => {
+			for (const projected of batch.artifacts) {
+				const existingId = this.store.resolveIdentity(producerId, projected.externalId);
+				if (existingId) {
+					this.artifacts.updateContent(existingId, { title: projected.title, body: projected.body, labels: projected.labels ? [...projected.labels] : undefined });
+					if (projected.extra !== undefined) this.artifacts.setExtra(existingId, projected.extra);
+				} else {
+					const created = this.artifacts.create({
+						kind: projected.kind,
+						subtype: projected.subtype,
+						title: projected.title,
+						body: projected.body,
+						labels: projected.labels ? [...projected.labels] : undefined,
+						extra: projected.extra,
+					});
+					this.store.recordIdentity(producerId, projected.externalId, created.id);
+					artifactsCreated++;
+				}
+				artifactsUpserted++;
+			}
+			for (const edge of batch.edges) {
+				const fromId = this.store.resolveIdentity(producerId, edge.from);
+				if (!fromId) throw new Error(`edge references unknown externalId "${edge.from}" for producer "${producerId}"`);
+				const toId = this.store.resolveIdentity(producerId, edge.to);
+				if (!toId) throw new Error(`edge references unknown externalId "${edge.to}" for producer "${producerId}"`);
+				this.artifacts.link({ from: fromId, relation: edge.relation, to: toId });
+				edgesUpserted++;
+			}
+			this.store.commitCheckpoint({ producerId, lastSequence: batch.sequence, lastBatchId: batchId, appliedAt: new Date().toISOString() });
+		});
+
+		return { producerId, batchId, sequence: batch.sequence, artifactsUpserted, artifactsCreated, edgesUpserted, alreadyApplied: false };
+	}
+}