@danypops/papyrus 0.56.0 → 0.57.0

package/src/db.ts

@@ -233,17 +233,34 @@ CREATE INDEX IF NOT EXISTS graph_projection_identities_artifact_idx ON graph_pro
 CREATE TABLE IF NOT EXISTS artifact_scopes (
 	artifact_id   TEXT PRIMARY KEY REFERENCES artifacts(id),
 	project_root  TEXT,
-	mode          TEXT NOT NULL DEFAULT 'global' CHECK (mode IN ('global', 'projects')),
+	mode          TEXT NOT NULL DEFAULT 'all' CHECK (mode IN ('none', 'all', 'explicit')),
 	source        TEXT NOT NULL CHECK (source IN ('cwd', 'explicit', 'unscoped')),
 	assigned_at   TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS artifact_scopes_project_idx ON artifact_scopes(project_root, artifact_id);
-CREATE TABLE IF NOT EXISTS artifact_scope_projects (
+CREATE TABLE IF NOT EXISTS artifact_scope_members (
 	artifact_id  TEXT NOT NULL REFERENCES artifacts(id) ON DELETE CASCADE,
-	project_id   TEXT NOT NULL REFERENCES task_projects(id),
-	PRIMARY KEY (artifact_id, project_id)
+	member_type  TEXT NOT NULL CHECK (member_type IN ('project', 'group')),
+	member_id    TEXT NOT NULL,
+	PRIMARY KEY (artifact_id, member_type, member_id)
 );
-CREATE INDEX IF NOT EXISTS artifact_scope_projects_project_idx ON artifact_scope_projects(project_id, artifact_id);
+CREATE INDEX IF NOT EXISTS artifact_scope_members_member_idx ON artifact_scope_members(member_type, member_id, artifact_id);
+CREATE TABLE IF NOT EXISTS scope_groups (
+	id            TEXT PRIMARY KEY,
+	name          TEXT NOT NULL,
+	aliases_json  TEXT NOT NULL DEFAULT '[]',
+	created_at    TEXT NOT NULL,
+	updated_at    TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS scope_groups_name_idx ON scope_groups(name);
+CREATE TABLE IF NOT EXISTS scope_group_members (
+	group_id     TEXT NOT NULL REFERENCES scope_groups(id) ON DELETE CASCADE,
+	member_type  TEXT NOT NULL CHECK (member_type IN ('project', 'group')),
+	member_id    TEXT NOT NULL,
+	PRIMARY KEY (group_id, member_type, member_id)
+);
+CREATE INDEX IF NOT EXISTS scope_group_members_group_idx ON scope_group_members(group_id);
+CREATE INDEX IF NOT EXISTS scope_group_members_member_idx ON scope_group_members(member_type, member_id);
 CREATE TABLE IF NOT EXISTS log_sources (
 	id            TEXT PRIMARY KEY,
 	label         TEXT NOT NULL,
@@ -864,7 +881,18 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 		// first if no Task ever used it either.
 		up: (db) => {
 			const existing = new Set((db.prepare("PRAGMA table_info(artifact_scopes)").all() as Array<{ name: string }>).map((row) => row.name));
-			if (!existing.has("mode")) {
+			// True only when migrating a genuinely pre-v28 database. A fixture that bootstraps from
+			// the CURRENT SCHEMA text (which already declares this column, in whatever its own current
+			// CHECK vocabulary is -- version 29 later widens/renames it from 'global'/'projects' to
+			// 'none'/'all'/'explicit') and then only fakes an older user_version to exercise an earlier
+			// migration's own path already has the column; forcing this migration's literal 'projects'
+			// value into it would violate version 29's tighter CHECK once that has shipped. The
+			// membership-table backfill below still always runs regardless (idempotent, and never
+			// touches the CHECK-restricted mode column itself) -- version 29's own remap pass detects
+			// "has a membership row" directly rather than trusting this flag's own mode literal, so a
+			// fixture that skips this exact write still ends up in the correct final 'explicit' state.
+			const columnPreexisted = existing.has("mode");
+			if (!columnPreexisted) {
 				db.exec("ALTER TABLE artifact_scopes ADD COLUMN mode TEXT NOT NULL DEFAULT 'global' CHECK (mode IN ('global', 'projects'))");
 			}
 			db.exec(`
@@ -893,11 +921,93 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 					const now = new Date().toISOString();
 					insertProject.run(projectId, basename(row.project_root) || row.project_root, row.project_root, now, now);
 				}
-				setProjectsMode.run(row.artifact_id);
+				if (!columnPreexisted) setProjectsMode.run(row.artifact_id);
 				insertMembership.run(row.artifact_id, projectId);
 			}
 		},
 	},
+	{
+		version: 29,
+		name: "artifact-scope-tri-state-and-scope-groups",
+		// See scope-group/. Adds the nested-scope-group registry (scope_groups/scope_group_members),
+		// and replaces artifact_scopes' two-state mode ('global'|'projects') with a real three-state
+		// one ('none'|'all'|'explicit') -- 'none' (fully hidden, never applicable) did not exist
+		// before this. SQLite has no ALTER TABLE ... CHECK, so artifact_scopes is rebuilt (copy with
+		// remapped mode values, drop, rename) rather than altered in place; every row's own
+		// artifact_id/project_root/source/assigned_at is preserved byte-for-byte, only `mode`'s
+		// values change (global->all, projects->explicit) and its CHECK constraint widens.
+		// artifact_scope_projects is folded into the new, kind-neutral artifact_scope_members
+		// (adding member_type so a membership row can name a project OR a scope group) --
+		// existing project memberships become member_type='project' rows, unchanged in meaning.
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS scope_groups (
+					id            TEXT PRIMARY KEY,
+					name          TEXT NOT NULL,
+					aliases_json  TEXT NOT NULL DEFAULT '[]',
+					created_at    TEXT NOT NULL,
+					updated_at    TEXT NOT NULL
+				);
+				CREATE INDEX IF NOT EXISTS scope_groups_name_idx ON scope_groups(name);
+				CREATE TABLE IF NOT EXISTS scope_group_members (
+					group_id     TEXT NOT NULL REFERENCES scope_groups(id) ON DELETE CASCADE,
+					member_type  TEXT NOT NULL CHECK (member_type IN ('project', 'group')),
+					member_id    TEXT NOT NULL,
+					PRIMARY KEY (group_id, member_type, member_id)
+				);
+				CREATE INDEX IF NOT EXISTS scope_group_members_group_idx ON scope_group_members(group_id);
+				CREATE INDEX IF NOT EXISTS scope_group_members_member_idx ON scope_group_members(member_type, member_id);
+			`);
+			// Guarded by whether the OLD artifact_scope_projects table still exists, the same class of
+			// concern version 16's/note-events' own comments cover: a fixture that bootstraps from the
+			// CURRENT SCHEMA text (which already declares artifact_scopes/artifact_scope_members in
+			// their POST-this-migration shape) and then only fakes an older user_version to exercise an
+			// earlier migration's own path must not attempt to rebuild a table that's already correctly
+			// shaped -- rebuilding it again with a CASE mode remap over already-new mode values ('all'/
+			// 'explicit') would violate the new CHECK, since those aren't 'global'/'projects' either.
+			const oldTableExists =
+				db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'artifact_scope_projects'").get() != null;
+			if (!oldTableExists) return;
+			db.exec(`
+				CREATE TABLE artifact_scopes_v29 (
+					artifact_id   TEXT PRIMARY KEY REFERENCES artifacts(id),
+					project_root  TEXT,
+					mode          TEXT NOT NULL DEFAULT 'all' CHECK (mode IN ('none', 'all', 'explicit')),
+					source        TEXT NOT NULL CHECK (source IN ('cwd', 'explicit', 'unscoped')),
+					assigned_at   TEXT NOT NULL
+				);
+				-- Keyed off real membership-row existence, not the old mode literal: v28's own write of
+				-- that literal is itself conditionally skipped (see its own comment) when replaying
+				-- against a fixture that already has this column in a later, tightened CHECK shape --
+				-- membership rows are still always backfilled unconditionally either way, so checking
+				-- for one directly is correct in every case, historical or fixture-simulated alike.
+				INSERT INTO artifact_scopes_v29 (artifact_id, project_root, mode, source, assigned_at)
+					SELECT s.artifact_id, s.project_root,
+						CASE
+							WHEN EXISTS (SELECT 1 FROM artifact_scope_projects p WHERE p.artifact_id = s.artifact_id) THEN 'explicit'
+							WHEN s.mode = 'global' THEN 'all'
+							WHEN s.mode = 'projects' THEN 'explicit'
+							ELSE s.mode
+						END,
+						s.source, s.assigned_at
+					FROM artifact_scopes s;
+				DROP TABLE artifact_scopes;
+				ALTER TABLE artifact_scopes_v29 RENAME TO artifact_scopes;
+				CREATE INDEX IF NOT EXISTS artifact_scopes_project_idx ON artifact_scopes(project_root, artifact_id);
+
+				CREATE TABLE IF NOT EXISTS artifact_scope_members (
+					artifact_id  TEXT NOT NULL REFERENCES artifacts(id) ON DELETE CASCADE,
+					member_type  TEXT NOT NULL CHECK (member_type IN ('project', 'group')),
+					member_id    TEXT NOT NULL,
+					PRIMARY KEY (artifact_id, member_type, member_id)
+				);
+				INSERT INTO artifact_scope_members (artifact_id, member_type, member_id)
+					SELECT artifact_id, 'project', project_id FROM artifact_scope_projects;
+				DROP TABLE artifact_scope_projects;
+				CREATE INDEX IF NOT EXISTS artifact_scope_members_member_idx ON artifact_scope_members(member_type, member_id, artifact_id);
+			`);
+		},
+	},
 ];
 
 /**

package/src/{stores → discussion}/discussion-round-store.ts

@@ -1,4 +1,4 @@
-import type { AppendDiscussionRound, DiscussionRound, DiscussionRoundQuery } from "../domain/discussion.ts";
+import type { AppendDiscussionRound, DiscussionRound, DiscussionRoundQuery } from "../discussion/discussion.ts";
 
 /** Persistence port for a Discussion's append-only rounds (see domain/discussion.ts). */
 export interface DiscussionRoundStore {

package/src/discussion/discussion-service.ts

@@ -21,8 +21,8 @@ import {
 	validateDiscussionOptions,
 	validateSelectedOptions,
 	validateSettlement,
-} from "../domain/discussion.ts";
-import type { DiscussionRoundStore } from "../stores/discussion-round-store.ts";
+} from "./discussion.ts";
+import type { DiscussionRoundStore } from "./discussion-round-store.ts";
 
 export class DiscussionError extends Error {}
 

package/src/{stores → discussion}/sqlite-discussion-round-store.ts

@@ -8,8 +8,8 @@ import {
 	validateDiscussionActor,
 	validateDiscussionContent,
 	validateDiscussionOptions,
-} from "../domain/discussion.ts";
-import type { DiscussionRoundStore } from "./discussion-round-store.ts";
+} from "../discussion/discussion.ts";
+import type { DiscussionRoundStore } from "../discussion/discussion-round-store.ts";
 
 interface DiscussionRoundRow {
 	id: number;

package/src/display-graph/graph-renderer.ts

@@ -0,0 +1,5 @@
+import type { DisplayGraph, RenderedGraph } from "../display-graph/display-graph.ts";
+
+export interface GraphRenderer {
+	render(graph: DisplayGraph): RenderedGraph;
+}

package/src/docs/docs-service.ts

@@ -9,23 +9,29 @@ import type { ArtifactEventContext } from "../artifact/artifact-event.ts";
 import type { ArtifactScope, ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { ArtifactAction, AuthorityRegistry } from "../authority-registry.ts";
-import { ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT } from "../constants.ts";
-import { resolveProjectReference } from "../domain/project-registry.ts";
-import { normalizeProjectRoot } from "../domain/task-scope.ts";
 import {
+	addArtifactScopeGroup,
+	addArtifactScopeProject,
 	assertBodyBounds,
 	assertLabelsBounds,
 	assertTitleBounds,
 	type ListFilter,
 	listScoped,
+	removeArtifactScopeGroup,
+	removeArtifactScopeProject,
+	replaceArtifactScopeGroups,
+	replaceArtifactScopeProjects,
 	requireContentUpdateFields,
 	requireKind,
 	runTransition,
+	setArtifactScopeNone,
 	type TransitionTable,
 	type UpdateContentInput,
 } from "../domain-service-shared.ts";
 import { NOTE_SUBTYPE } from "../note/note-service.ts";
-import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
+import type { ProjectRegistryStore } from "../project-registry/project-registry-store.ts";
+import type { ScopeGroupStore } from "../scope-group/scope-group-store.ts";
+import { normalizeProjectRoot } from "../task-scope/task-scope.ts";
 
 function rejectsNoteTemplate(artifacts: ArtifactStore, templateId: string | undefined, subtype: string | undefined): boolean {
 	if (subtype === NOTE_SUBTYPE) return true;
@@ -117,11 +123,7 @@ export function createDocument(
 		context,
 	);
 	if (input.projectReferences !== undefined && input.projectReferences.length > 0) {
-		if (input.projectReferences.length > ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
-			throw new Error(`projectReferences may include at most ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} entries`);
-		}
-		const ids = input.projectReferences.map((reference) => resolveProjectReference(registry!, reference).id);
-		scopes.replaceProjects(document.id, ids, "explicit");
+		replaceArtifactScopeProjects(scopes, registry!, document.id, input.projectReferences);
 	} else {
 		scopes.assign(document.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
 	}
@@ -163,7 +165,13 @@ export function docScope(artifacts: ArtifactStore, scopes: ArtifactScopeStore, i
 
 export function setDocGlobal(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string): ArtifactScope {
 	requireDocument(artifacts, id);
-	return scopes.setGlobal(id, "explicit");
+	return scopes.setAll(id, "explicit");
+}
+
+/** Fully hides this Doc -- never applicable, never context-injected, regardless of project. The only new mode beyond the pre-existing global/projects pair. */
+export function setDocNone(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string): ArtifactScope {
+	requireDocument(artifacts, id);
+	return setArtifactScopeNone(scopes, id);
 }
 
 export function replaceDocProjects(
@@ -174,12 +182,7 @@ export function replaceDocProjects(
 	projectReferences: readonly string[],
 ): ArtifactScope {
 	requireDocument(artifacts, id);
-	if (projectReferences.length === 0) throw new Error("projectReferences must be non-empty; use docs.set_global to clear scoping");
-	if (projectReferences.length > ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
-		throw new Error(`projectReferences may include at most ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} entries`);
-	}
-	const ids = projectReferences.map((reference) => resolveProjectReference(registry, reference).id);
-	return scopes.replaceProjects(id, ids, "explicit");
+	return replaceArtifactScopeProjects(scopes, registry, id, projectReferences);
 }
 
 export function addDocProject(
@@ -190,8 +193,7 @@ export function addDocProject(
 	projectReference: string,
 ): ArtifactScope {
 	requireDocument(artifacts, id);
-	const project = resolveProjectReference(registry, projectReference);
-	return scopes.addProject(id, project.id, "explicit");
+	return addArtifactScopeProject(scopes, registry, id, projectReference);
 }
 
 export function removeDocProject(
@@ -202,8 +204,41 @@ export function removeDocProject(
 	projectReference: string,
 ): ArtifactScope {
 	requireDocument(artifacts, id);
-	const project = resolveProjectReference(registry, projectReference);
-	return scopes.removeProject(id, project.id);
+	return removeArtifactScopeProject(scopes, registry, id, projectReference);
+}
+
+/** Scope-group ('nested scope') siblings of replaceDocProjects/addDocProject/removeDocProject -- same Note-rejecting Doc guard, delegating the actual reference-resolution and store call to the shared, kind-agnostic helpers. */
+export function replaceDocGroups(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	scopeGroups: ScopeGroupStore,
+	id: string,
+	groupReferences: readonly string[],
+): ArtifactScope {
+	requireDocument(artifacts, id);
+	return replaceArtifactScopeGroups(scopes, scopeGroups, id, groupReferences);
+}
+
+export function addDocGroup(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	scopeGroups: ScopeGroupStore,
+	id: string,
+	groupReference: string,
+): ArtifactScope {
+	requireDocument(artifacts, id);
+	return addArtifactScopeGroup(scopes, scopeGroups, id, groupReference);
+}
+
+export function removeDocGroup(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	scopeGroups: ScopeGroupStore,
+	id: string,
+	groupReference: string,
+): ArtifactScope {
+	requireDocument(artifacts, id);
+	return removeArtifactScopeGroup(scopes, scopeGroups, id, groupReference);
 }
 
 function requireDocument(artifacts: ArtifactStore, id: string): Artifact {

package/src/domain-service-shared.ts

@@ -7,16 +7,21 @@
 
 import type { Artifact } from "./artifact/artifact.ts";
 import type { ArtifactEventContext } from "./artifact/artifact-event.ts";
-import type { ArtifactScopeStore } from "./artifact/artifact-scope-store.ts";
+import type { ArtifactScope, ArtifactScopeStore } from "./artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "./artifact/artifact-store.ts";
 import {
 	ARTIFACT_BODY_MAX_LENGTH,
 	ARTIFACT_LABEL_MAX_COUNT,
 	ARTIFACT_LABEL_MAX_LENGTH,
 	ARTIFACT_SCOPE_MAX_ARTIFACTS,
+	ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT,
 	ARTIFACT_TITLE_MAX_LENGTH,
 } from "./constants.ts";
-import { normalizeProjectRoot } from "./domain/task-scope.ts";
+import { resolveProjectReference } from "./project-registry/project-registry.ts";
+import type { ProjectRegistryStore } from "./project-registry/project-registry-store.ts";
+import { resolveScopeGroupReference } from "./scope-group/scope-group.ts";
+import type { ScopeGroupStore } from "./scope-group/scope-group-store.ts";
+import { normalizeProjectRoot } from "./task-scope/task-scope.ts";
 
 export interface UpdateContentInput {
 	title?: string;
@@ -181,3 +186,86 @@ export function assignArtifactProject(
 	);
 	return artifacts.get(id)!;
 }
+
+/**
+ * Kind-agnostic scope-mutation primitives shared by docs/rules/playbook-service.ts's own thin,
+ * per-kind wrappers (each of which validates the artifact's own kind/subtype first -- e.g.
+ * requireDocument's Note exclusion -- then delegates here for the actual reference-resolution +
+ * bounds-check + store-call, which is genuinely identical across every kind). Mirrors
+ * assignArtifactProject's own already-established split, extended to the tri-state
+ * none/all/explicit model and to scope groups ('nested scopes').
+ */
+export function setArtifactScopeNone(scopes: ArtifactScopeStore, artifactId: string): ArtifactScope {
+	return scopes.setNone(artifactId, "explicit");
+}
+
+export function replaceArtifactScopeProjects(
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	artifactId: string,
+	projectReferences: readonly string[],
+): ArtifactScope {
+	if (projectReferences.length === 0) throw new Error("projectReferences must be non-empty; use set_none/set_global to clear scoping");
+	if (projectReferences.length > ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT) {
+		throw new Error(`projectReferences may include at most ${ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT} entries`);
+	}
+	const members = projectReferences.map((reference) => ({ type: "project" as const, id: resolveProjectReference(registry, reference).id }));
+	return scopes.replaceMembers(artifactId, members, "explicit");
+}
+
+export function addArtifactScopeProject(
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	artifactId: string,
+	projectReference: string,
+): ArtifactScope {
+	const project = resolveProjectReference(registry, projectReference);
+	return scopes.addMember(artifactId, { type: "project", id: project.id }, "explicit");
+}
+
+export function removeArtifactScopeProject(
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	artifactId: string,
+	projectReference: string,
+): ArtifactScope {
+	const project = resolveProjectReference(registry, projectReference);
+	return scopes.removeMember(artifactId, { type: "project", id: project.id });
+}
+
+export function replaceArtifactScopeGroups(
+	scopes: ArtifactScopeStore,
+	scopeGroups: ScopeGroupStore,
+	artifactId: string,
+	groupReferences: readonly string[],
+): ArtifactScope {
+	if (groupReferences.length === 0) throw new Error("groupReferences must be non-empty; use set_none/set_global to clear scoping");
+	if (groupReferences.length > ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT) {
+		throw new Error(`groupReferences may include at most ${ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT} entries`);
+	}
+	const members = groupReferences.map((reference) => ({
+		type: "group" as const,
+		id: resolveScopeGroupReference(scopeGroups, reference).id,
+	}));
+	return scopes.replaceMembers(artifactId, members, "explicit");
+}
+
+export function addArtifactScopeGroup(
+	scopes: ArtifactScopeStore,
+	scopeGroups: ScopeGroupStore,
+	artifactId: string,
+	groupReference: string,
+): ArtifactScope {
+	const group = resolveScopeGroupReference(scopeGroups, groupReference);
+	return scopes.addMember(artifactId, { type: "group", id: group.id }, "explicit");
+}
+
+export function removeArtifactScopeGroup(
+	scopes: ArtifactScopeStore,
+	scopeGroups: ScopeGroupStore,
+	artifactId: string,
+	groupReference: string,
+): ArtifactScope {
+	const group = resolveScopeGroupReference(scopeGroups, groupReference);
+	return scopes.removeMember(artifactId, { type: "group", id: group.id });
+}

package/src/{domain → gate}/gate-execution.ts

@@ -26,8 +26,8 @@ import {
 	GATE_TEST_TIMEOUT_MS,
 } from "../constants.ts";
 import type { Db } from "../db.ts";
+import type { Gate, GateResult, GateRunOptions } from "../gate/gate.ts";
 import { getArtifact } from "../ops.ts";
-import type { Gate, GateResult, GateRunOptions } from "./gate.ts";
 
 const require_ = createRequire(import.meta.url);
 

package/src/{stores → gate}/gate-runner.ts

@@ -1,4 +1,4 @@
-import type { GateResult, GateRunOptions } from "../domain/gate.ts";
+import type { GateResult, GateRunOptions } from "../gate/gate.ts";
 
 export interface GateRunner {
 	run(artifactId: string, options?: GateRunOptions): GateResult[];

package/src/{stores → gate}/sqlite-gate-runner.ts

@@ -1,7 +1,7 @@
 import type { Db } from "../db.ts";
-import type { GateResult, GateRunOptions } from "../domain/gate.ts";
-import { runGates, runGatesAsync } from "../domain/gate-execution.ts";
-import type { GateRunner } from "./gate-runner.ts";
+import type { GateResult, GateRunOptions } from "../gate/gate.ts";
+import { runGates, runGatesAsync } from "../gate/gate-execution.ts";
+import type { GateRunner } from "../gate/gate-runner.ts";
 
 export class SQLiteGateRunner implements GateRunner {
 	constructor(private readonly db: Db) {}

package/src/graph-projection/graph-projection-service.ts

@@ -12,8 +12,8 @@ import {
 	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 { GraphProjectionStore } from "../stores/graph-projection-store.ts";
+import { GRAPH_PROJECTION_SCHEMA_VERSION, type GraphProjectionBatch, type GraphProjectionResult } from "./graph-projection.ts";
+import type { GraphProjectionStore } from "./graph-projection-store.ts";
 
 function boundedId(value: string, label: string): string {
 	if (!value || value.length === 0) throw new Error(`${label} is required`);

package/src/{stores → graph-projection}/graph-projection-store.ts

@@ -1,4 +1,4 @@
-import type { ProjectionCheckpoint } from "../domain/graph-projection.ts";
+import type { ProjectionCheckpoint } from "../graph-projection/graph-projection.ts";
 
 /**
  * Producer-scoped state a graph projection consumer needs beyond the generic ArtifactStore:

package/src/{stores → graph-projection}/sqlite-graph-projection-store.ts

@@ -1,7 +1,7 @@
 import type { Db } from "../db.ts";
 import { inTransaction } from "../db.ts";
-import type { ProjectionCheckpoint } from "../domain/graph-projection.ts";
-import type { GraphProjectionStore } from "./graph-projection-store.ts";
+import type { ProjectionCheckpoint } from "../graph-projection/graph-projection.ts";
+import type { GraphProjectionStore } from "../graph-projection/graph-projection-store.ts";
 
 export class SQLiteGraphProjectionStore implements GraphProjectionStore {
 	constructor(private readonly db: Db) {}

package/src/handlers/discuss.ts

@@ -18,8 +18,8 @@ import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH, DISCUSSION_OPTION_MAX_LENGTH, DISCUSSION_OPTIONS_MAX_COUNT } from "../constants.ts";
+import { DISCUSSION_SUBTYPE, type DiscussionRound } from "../discussion/discussion.ts";
 import type { DiscussionAndRounds, Discussions } from "../discussion/discussion-service.ts";
-import { DISCUSSION_SUBTYPE, type DiscussionRound } from "../domain/discussion.ts";
 import { discussOperations } from "../modules/discuss.ts";
 import {
 	createOperationDefiner,

package/src/handlers/docs.ts

@@ -9,7 +9,8 @@ import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
 import { listDocuments } from "../docs/docs-service.ts";
 import { docsOperations } from "../modules/docs.ts";
-import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
+import type { ProjectRegistryStore } from "../project-registry/project-registry-store.ts";
+import type { ScopeGroupStore } from "../scope-group/scope-group-store.ts";
 import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "docs";
@@ -54,8 +55,9 @@ export function registerDocsVehicleOperations(
 	scopes: ArtifactScopeStore,
 	authority: AuthorityRegistry,
 	projectRegistry: ProjectRegistryStore,
+	scopeGroups: ScopeGroupStore,
 ): void {
-	const moduleOperations = new Map(docsOperations(artifacts, scopes, authority, projectRegistry).map((op) => [op.name, op]));
+	const moduleOperations = new Map(docsOperations(artifacts, scopes, authority, projectRegistry, scopeGroups).map((op) => [op.name, op]));
 	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
 	const define = createOperationDefiner(registry, OWNER, "docs", ["docs:read", "docs:write"], call);
 
@@ -209,6 +211,59 @@ export function registerDocsVehicleOperations(
 		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
 	);
 
+	define(
+		"set_none",
+		"Fully hides a Doc -- never applicable, never context-injected, regardless of project. The only way back is set_global, add_project, add_group, or replace_projects/replace_groups.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"add_group",
+		"Adds one scope group (a named, reusable, possibly-nested collection of projects and/or other groups) to a Doc's explicit scope, switching it from global/none to project-bound if it wasn't already. Idempotent if the group is already a member.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			group: { ...stringProp, description: "Exact scope group id, name, or alias to add." },
+			project_root: stringProp,
+		},
+		["group"],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"remove_group",
+		"Removes one scope group from a Doc's explicit scope. Rejected while it is the Doc's only remaining scope member -- call set_global or set_none first.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			group: { ...stringProp, description: "Exact scope group id, name, or alias to remove." },
+			project_root: stringProp,
+		},
+		["group"],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"replace_groups",
+		"Replaces a Doc's entire scope-group membership with exactly this bounded, non-empty list of scope group references (id/name/alias). Use set_global/set_none instead to clear scoping entirely.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			groups: { type: "array", description: "Non-empty list of exact scope group id/name/alias references." } as unknown as {
+				type: string;
+			},
+			project_root: stringProp,
+		},
+		["groups"],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
 	define(
 		"update",
 		"Changes a Doc's title/body/labels (at least one required). Refused for a read-only external projection (e.g. web-spider-ingested Docs) -- capture a correction as a new linked Doc instead.",