@okfit/engine 0.9.4 → 0.11.0

package/index.js

@@ -1,5 +1,5 @@
 import { resolveBundleRoot, resolveProjectRoot } from "./config/anchor.js";
-import { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "./errors.js";
+import { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, QueryConceptNotFoundError, QuerySelectionError, QueryUnknownVocabularyError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "./errors.js";
 import { buildConfigLayer, provideConfig } from "./config/layer.js";
 import { DEFAULT_PROFILE_NAME, resolveProjectConfig } from "./config/resolve.js";
 import { runContext } from "./context/run.js";
@@ -10,6 +10,7 @@ import { CONFIG_RELATIVE_PATH, configValue, files, targetPaths } from "./init/sc
 import { OverlayDocuments, layerOverlayFileSystem, makeOverlayFileSystem } from "./overlay/layer.js";
 import { provideDocuments, resolveDocumentPath } from "./overlay/documents.js";
 import { OkfitPlatform } from "./platform.js";
+import { ConceptQuery } from "./query/ConceptQuery.js";
 import { ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, contextEnvelope } from "./render/context.js";
 import { DistributionField } from "./render/distribution.js";
 import { forDiagnostics, tally } from "./render/exit.js";
@@ -17,6 +18,7 @@ import { ENGINE_VERSION } from "./version.js";
 import { GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, graphEnvelope } from "./render/graph.js";
 import { collect, sort } from "./render/sort.js";
 import { JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, json, jsonError } from "./render/json.js";
+import { ConceptSummary, QueryGetEnvelope, QueryLink, QueryListEnvelope, QueryNeighbor, QueryNeighborsEnvelope, queryGetEnvelope, queryListEnvelope, queryNeighborsEnvelope, toConceptSummary } from "./render/query.js";
 import { StaleEnvelope, StaleItem, StaleSummary, staleEnvelope } from "./render/stale.js";
 import { SkipReason, runSync } from "./sync/run.js";
 import { SyncEnvelope, SyncModeEnvelope, syncEnvelope } from "./render/sync.js";
@@ -26,6 +28,7 @@ import { conceptFor } from "./session/concept.js";
 import { withFallbackRange } from "./session/range.js";
 import { BundleSession } from "./session/BundleSession.js";
 import { runStale } from "./stale/run.js";
-import { runVerify, runVerifyBatch } from "./verify/run.js";
+import { resolveBatchTypes, selectAttestable, selectPickerCandidates } from "./verify/select.js";
+import { loadPickerCandidates, runVerify, runVerifyBatch, runVerifyIds } from "./verify/run.js";
 
-export { BundleSession, CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, DistributionField, DocumentPathError, ENGINE_VERSION, ExternalReferences, FrontmatterEdits, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, OverlayDocuments, ReferenceCheck, ReferenceState, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, SyncStagedLogError, UnsupportedFrontmatterError, VerifyBatchEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifySelectionError, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, conceptFor, configValue, contextEnvelope, files, forDiagnostics, graphEnvelope, json, jsonError, layerOverlayFileSystem, makeOverlayFileSystem, provideConfig, provideDocuments, resolveBundleRoot, resolveDocumentPath, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, runVerifyBatch, sort, staleEnvelope, syncEnvelope, tally, targetPaths, verifyBatchEnvelope, verifyEnvelope, withFallbackRange };
+export { BundleSession, CONFIG_RELATIVE_PATH, ConceptQuery, ConceptSummary, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, DistributionField, DocumentPathError, ENGINE_VERSION, ExternalReferences, FrontmatterEdits, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, OverlayDocuments, QueryConceptNotFoundError, QueryGetEnvelope, QueryLink, QueryListEnvelope, QueryNeighbor, QueryNeighborsEnvelope, QuerySelectionError, QueryUnknownVocabularyError, ReferenceCheck, ReferenceState, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, SyncStagedLogError, UnsupportedFrontmatterError, VerifyBatchEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifySelectionError, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, conceptFor, configValue, contextEnvelope, files, forDiagnostics, graphEnvelope, json, jsonError, layerOverlayFileSystem, loadPickerCandidates, makeOverlayFileSystem, provideConfig, provideDocuments, queryGetEnvelope, queryListEnvelope, queryNeighborsEnvelope, resolveBatchTypes, resolveBundleRoot, resolveDocumentPath, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, runVerifyBatch, runVerifyIds, selectAttestable, selectPickerCandidates, sort, staleEnvelope, syncEnvelope, tally, targetPaths, toConceptSummary, verifyBatchEnvelope, verifyEnvelope, withFallbackRange };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/engine",
-	"version": "0.9.4",
+	"version": "0.11.0",
 	"private": false,
 	"description": "The okfit engine: platform layer, config discovery, and the validate, verify, sync, init and context programs shared by the okfit CLI and MCP server.",
 	"keywords": [
@@ -34,23 +34,23 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effect/platform-node": "4.0.0-rc.118",
-		"@effected/app": "^0.19.0",
-		"@effected/config-file": "^0.13.1",
-		"@effected/engine": "^0.2.0",
-		"@effected/git": "^0.19.0",
-		"@effected/glob": "^0.9.0",
-		"@effected/jsonc": "^0.14.0",
-		"@effected/markdown": "^0.14.0",
-		"@effected/schemastore": "^0.17.0",
-		"@effected/store": "^0.11.0",
-		"@effected/toml": "^0.10.0",
-		"@effected/walker": "^0.14.0",
-		"@effected/xdg": "^0.8.2",
-		"@effected/yaml": "^0.18.0",
-		"@okfit/core": "0.8.3",
-		"@okfit/profiles": "0.8.2",
-		"effect": "4.0.0-rc.118"
+		"@effect/platform-node": "^4.0.0",
+		"@effected/app": "^0.20.0",
+		"@effected/config-file": "^0.14.0",
+		"@effected/engine": "^0.3.0",
+		"@effected/git": "^0.20.0",
+		"@effected/glob": "^0.10.0",
+		"@effected/jsonc": "^0.15.0",
+		"@effected/markdown": "^0.15.0",
+		"@effected/schemastore": "^0.18.0",
+		"@effected/store": "^0.12.0",
+		"@effected/toml": "^0.11.0",
+		"@effected/walker": "^0.15.0",
+		"@effected/xdg": "^0.9.0",
+		"@effected/yaml": "^0.19.0",
+		"@okfit/core": "0.8.4",
+		"@okfit/profiles": "0.8.3",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/query/ConceptQuery.js

@@ -0,0 +1,102 @@
+import { QueryConceptNotFoundError, QueryUnknownVocabularyError } from "../errors.js";
+import { ConceptId, Derive, Graph } from "@okfit/core";
+import { Effect, Option } from "effect";
+
+//#region src/query/ConceptQuery.ts
+const byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+const resolve = (bundle, rawId) => Effect.gen(function* () {
+	const normalized = ConceptId.normalize(rawId);
+	if (Option.isNone(normalized)) return yield* Effect.fail(new QueryConceptNotFoundError({
+		id: rawId,
+		reason: "empty-id"
+	}));
+	const id = normalized.value;
+	const concept = bundle.concepts.get(id);
+	if (concept === void 0) return yield* Effect.fail(new QueryConceptNotFoundError({
+		id: rawId,
+		reason: "not-a-concept"
+	}));
+	return {
+		id,
+		concept
+	};
+});
+/**
+* Read-only queries over a loaded bundle, shared by `okfit query` and the MCP
+* tools.
+*
+* @public
+*/
+const ConceptQuery = {
+	/** Validates types then tags against config (first unknown fails), then filters and sorts by id. */
+	list: (bundle, config, filter) => Effect.gen(function* () {
+		const declaredTypes = Object.keys(config.types ?? {}).toSorted();
+		const declaredTags = Object.keys(config.tags ?? {}).toSorted();
+		const types = filter.types ?? [];
+		for (const type of types) if (!declaredTypes.includes(type)) return yield* Effect.fail(new QueryUnknownVocabularyError({
+			kind: "type",
+			requested: type,
+			valid: declaredTypes
+		}));
+		const requestedTags = filter.tags ?? [];
+		for (const tag of requestedTags) if (!declaredTags.includes(tag)) return yield* Effect.fail(new QueryUnknownVocabularyError({
+			kind: "tag",
+			requested: tag,
+			valid: declaredTags
+		}));
+		const statuses = filter.statuses ?? [];
+		return [...bundle.concepts.values()].filter((concept) => {
+			if (types.length > 0 && !types.includes(concept.frontmatter.type)) return false;
+			const tags = concept.frontmatter.tags ?? [];
+			if (!requestedTags.every((tag) => tags.includes(tag))) return false;
+			if (statuses.length > 0 && !statuses.includes(Derive.status(concept.frontmatter))) return false;
+			if (filter.verified !== void 0) {
+				if ((concept.frontmatter.verified ?? []).length > 0 !== filter.verified) return false;
+			}
+			return true;
+		}).toSorted(byId);
+	}),
+	/** One concept by tolerant id, with its outgoing links. */
+	get: (bundle, id) => Effect.gen(function* () {
+		const resolved = yield* resolve(bundle, id);
+		const graph = Graph.fromBundle(bundle);
+		const links = graph.edges.filter((edge) => edge.from === resolved.id).map((edge) => ({
+			to: edge.to,
+			kind: Option.match(graph.node(edge.to), {
+				onNone: () => "missing",
+				onSome: (node) => node.kind
+			}),
+			source: edge.data.source,
+			...edge.data.field === void 0 ? {} : { field: edge.data.field }
+		}));
+		return {
+			concept: resolved.concept,
+			links
+		};
+	}),
+	/** Outgoing and incoming graph neighbours of one concept. */
+	neighbors: (bundle, id) => Effect.gen(function* () {
+		const resolved = yield* resolve(bundle, id);
+		const graph = Graph.fromBundle(bundle);
+		const project = (node) => {
+			if (node.kind !== "concept") return {
+				id: node.id,
+				kind: node.kind,
+				concept: null
+			};
+			return {
+				id: node.id,
+				kind: node.kind,
+				concept: bundle.concepts.get(node.id) ?? null
+			};
+		};
+		return {
+			id: resolved.id,
+			outgoing: graph.successors(resolved.id).map(project),
+			incoming: graph.predecessors(resolved.id).map(project)
+		};
+	})
+};
+
+//#endregion
+export { ConceptQuery };

package/render/query.js

@@ -0,0 +1,104 @@
+import { DistributionField } from "./distribution.js";
+import { ENGINE_VERSION } from "../version.js";
+import { Derive, GraphNodeKind, Status } from "@okfit/core";
+import { Schema } from "effect";
+
+//#region src/render/query.ts
+/** The seven-field shape every list-like query result carries (N-16). @public */
+const ConceptSummary = Schema.Struct({
+	id: Schema.String,
+	type: Schema.String,
+	title: Schema.String,
+	description: Schema.NullOr(Schema.String),
+	status: Status,
+	tags: Schema.Array(Schema.String),
+	path: Schema.String
+});
+/** Project one loaded concept into its summary. @public */
+const toConceptSummary = (concept) => ({
+	id: concept.id,
+	type: concept.frontmatter.type,
+	title: Derive.title(concept),
+	description: concept.frontmatter.description ?? null,
+	status: Derive.status(concept.frontmatter),
+	tags: [...concept.frontmatter.tags ?? []],
+	path: concept.path
+});
+/** `okfit query list --format json`'s envelope, schema 1, snake_case. @public */
+const QueryListEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	engine_version: Schema.String,
+	distribution: DistributionField,
+	total: Schema.Int,
+	items: Schema.Array(ConceptSummary)
+});
+/** One outgoing link of a concept, as `okfit query get` reports it. @public */
+const QueryLink = Schema.Struct({
+	to: Schema.String,
+	kind: GraphNodeKind,
+	source: Schema.Literals(["body", "frontmatter"]),
+	field: Schema.optionalKey(Schema.String)
+});
+/** `okfit query get --format json`'s envelope, schema 1, snake_case. @public */
+const QueryGetEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	engine_version: Schema.String,
+	distribution: DistributionField,
+	concept: Schema.Struct({
+		...ConceptSummary.fields,
+		frontmatter: Schema.Record(Schema.String, Schema.Unknown),
+		links: Schema.Array(QueryLink)
+	})
+});
+/** One neighbour of a concept; `summary` is `null` for a non-concept node. @public */
+const QueryNeighbor = Schema.Struct({
+	id: Schema.String,
+	kind: GraphNodeKind,
+	summary: Schema.NullOr(ConceptSummary)
+});
+/** `okfit query neighbors --format json`'s envelope, schema 1, snake_case. @public */
+const QueryNeighborsEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	engine_version: Schema.String,
+	distribution: DistributionField,
+	id: Schema.String,
+	outgoing: Schema.Array(QueryNeighbor),
+	incoming: Schema.Array(QueryNeighbor)
+});
+/** Build the list envelope; `items` is the already-paged, already-sorted summaries. @public */
+const queryListEnvelope = (input) => ({
+	schema: 1,
+	okfit_version: input.okfitVersion,
+	engine_version: ENGINE_VERSION,
+	distribution: input.distribution ?? null,
+	total: input.total,
+	items: input.items
+});
+/** Build the get envelope from a summary, the raw frontmatter and the outgoing links. @public */
+const queryGetEnvelope = (input) => ({
+	schema: 1,
+	okfit_version: input.okfitVersion,
+	engine_version: ENGINE_VERSION,
+	distribution: input.distribution ?? null,
+	concept: {
+		...input.concept,
+		frontmatter: input.frontmatter,
+		links: input.links
+	}
+});
+/** Build the neighbors envelope. @public */
+const queryNeighborsEnvelope = (input) => ({
+	schema: 1,
+	okfit_version: input.okfitVersion,
+	engine_version: ENGINE_VERSION,
+	distribution: input.distribution ?? null,
+	id: input.id,
+	outgoing: input.outgoing,
+	incoming: input.incoming
+});
+
+//#endregion
+export { ConceptSummary, QueryGetEnvelope, QueryLink, QueryListEnvelope, QueryNeighbor, QueryNeighborsEnvelope, queryGetEnvelope, queryListEnvelope, queryNeighborsEnvelope, toConceptSummary };

package/render/verify.js

@@ -1,5 +1,6 @@
 import { DistributionField } from "./distribution.js";
 import { ENGINE_VERSION } from "../version.js";
+import { Status } from "@okfit/core";
 import { Schema } from "effect";
 
 //#region src/render/verify.ts
@@ -23,6 +24,11 @@ const VerifyEnvelope = Schema.Struct({
 		by: Schema.String,
 		at: Schema.String
 	}),
+	/** Issue #185: the status change `--stable`/`--draft` made; `null` when neither flag was given. */
+	status: Schema.NullOr(Schema.Struct({
+		from: Schema.NullOr(Status),
+		to: Schema.Literals(["stable", "draft"])
+	})),
 	dry_run: Schema.Boolean,
 	exit_code: Schema.Literal(0)
 });
@@ -45,6 +51,7 @@ const verifyEnvelope = (input) => ({
 		by: input.by,
 		at: input.at
 	},
+	status: input.status,
 	dry_run: input.dryRun,
 	exit_code: 0
 });
@@ -69,7 +76,11 @@ const VerifyBatchEnvelope = Schema.Struct({
 	})),
 	skipped: Schema.Array(Schema.Struct({
 		id: Schema.String,
-		reason: Schema.Literals(["draft", "already-verified"])
+		reason: Schema.Literals([
+			"draft",
+			"deprecated",
+			"already-verified"
+		])
 	})),
 	dry_run: Schema.Boolean,
 	exit_code: Schema.Literal(0)

package/verify/run.js

@@ -1,6 +1,7 @@
-import { VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "../errors.js";
-import { documentNewline, locate, stripBom } from "./locate.js";
-import { splice } from "./splice.js";
+import { VerifyConceptNotFoundError, VerifyUnsupportedFrontmatterError } from "../errors.js";
+import { documentNewline, locate, locateTopLevelScalar, stripBom } from "./locate.js";
+import { mergeSameOffset, splice, spliceTopLevelScalar } from "./splice.js";
+import { resolveBatchTypes, selectAttestable, selectPickerCandidates } from "./select.js";
 import { Bundle, ConceptId, Timestamp } from "@okfit/core";
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
 import { Derivation } from "@okfit/profiles";
@@ -24,25 +25,39 @@ const UNDECODABLE_CODES = /* @__PURE__ */ new Set([
 	"type-missing"
 ]);
 /** Steps 9-14 of runVerify: read, locate (fail closed), splice; no write. */
-const prepareVerify = Effect.fn("okfit/verify/prepareVerify")(function* (bundle, concept, actor, at) {
+const prepareVerify = Effect.fn("okfit/verify/prepareVerify")(function* (bundle, concept, actor, at, status) {
 	const fs = yield* FileSystem.FileSystem;
 	const absolutePath = (yield* Path.Path).join(bundle.root, concept.path);
-	const source = yield* fs.readFileString(absolutePath);
+	const source = new TextDecoder("utf-8", { ignoreBOM: true }).decode(yield* fs.readFile(absolutePath));
 	const { text, bom } = stripBom(source);
 	const located = yield* locate(text);
 	if (located._tag === "unsupported") return yield* new VerifyUnsupportedFrontmatterError({
 		id: concept.id,
-		shape: located.shape
+		shape: located.shape,
+		key: "verified"
 	});
 	const priorAt = (concept.frontmatter.verified ?? []).filter((entry) => entry.by === actor).map((entry) => Schema.encodeSync(Timestamp)(entry.at));
-	const edit = splice(located, {
+	const newline = documentNewline(text);
+	const verifiedEdit = splice(located, {
 		by: actor,
 		at
-	}, documentNewline(text));
+	}, newline);
+	let statusEdit;
+	if (status !== void 0 && concept.frontmatter.status !== status) {
+		const target = yield* locateTopLevelScalar(text, "status");
+		if (target._tag === "unsupported") return yield* new VerifyUnsupportedFrontmatterError({
+			id: concept.id,
+			shape: target.shape,
+			key: "status"
+		});
+		statusEdit = spliceTopLevelScalar(target, "status", status, newline);
+	}
+	const edits = mergeSameOffset([verifiedEdit, ...statusEdit === void 0 ? [] : [statusEdit]].toSorted((a, b) => a.offset - b.offset || (a === statusEdit ? -1 : b === statusEdit ? 1 : 0)));
 	return {
 		absolutePath,
-		finalText: bom + MarkdownEdit.applyAll(text, [edit]),
-		fragment: edit.content,
+		finalText: bom + MarkdownEdit.applyAll(text, edits),
+		fragment: verifiedEdit.content,
+		statusFragment: statusEdit?.content ?? null,
 		priorAt
 	};
 });
@@ -56,21 +71,11 @@ const writeVerified = Effect.fn("okfit/verify/writeVerified")(function* (absolut
 	yield* fs.chmod(tempPath, original.mode);
 	yield* fs.rename(tempPath, target).pipe(Effect.onError(() => fs.remove(tempPath, { force: true }).pipe(Effect.ignore)));
 });
-/**
-* Contract §2.3 steps 6–15. Loads the bundle, resolves the id, resolves the
-* human actor from git, splices exactly one entry into the concept's
-* frontmatter and writes it back atomically.
-*
-* Nothing here reads `status`, `stale_after`, or a type's
-* `require_verified`: `verify` is mechanical, not config-aware (V-4, V-5).
-*
-* @internal
-*/
-const runVerify = Effect.fn("okfit/verify/runVerify")(function* (options) {
-	const bundle = yield* Bundle.load({ root: options.bundleRoot });
-	const normalized = ConceptId.normalize(options.id);
+/** Steps 7a-7d of runVerify, shared with `runVerifyIds`: tolerant id, reserved file, located concept. */
+const resolveConcept = (bundle, rawId) => Effect.gen(function* () {
+	const normalized = ConceptId.normalize(rawId);
 	if (Option.isNone(normalized)) return yield* new VerifyConceptNotFoundError({
-		id: options.id,
+		id: rawId,
 		root: bundle.root,
 		reason: "not-a-concept"
 	});
@@ -93,13 +98,32 @@ const runVerify = Effect.fn("okfit/verify/runVerify")(function* (options) {
 			}
 		});
 	}
+	return {
+		id,
+		concept
+	};
+});
+/**
+* Contract §2.3 steps 6–15. Loads the bundle, resolves the id, resolves the
+* human actor from git, splices exactly one entry into the concept's
+* frontmatter and writes it back atomically.
+*
+* Nothing here reads `stale_after` or a type's `require_verified`; `status`
+* is read only to skip a no-op edit under `options.status` (#185). `verify`
+* is mechanical, not config-aware (V-4, V-5).
+*
+* @internal
+*/
+const runVerify = Effect.fn("okfit/verify/runVerify")(function* (options) {
+	const bundle = yield* Bundle.load({ root: options.bundleRoot });
+	const { id, concept } = yield* resolveConcept(bundle, options.id);
 	const actor = yield* Derivation.generatedBy({
 		writer: "human",
 		cwd: options.projectRoot,
 		config: options.config
 	});
 	const at = Schema.encodeSync(Timestamp)(options.at);
-	const prepared = yield* prepareVerify(bundle, concept, actor, at);
+	const prepared = yield* prepareVerify(bundle, concept, actor, at, options.status);
 	if (!options.dryRun) yield* writeVerified(prepared.absolutePath, prepared.finalText);
 	return {
 		id,
@@ -109,13 +133,18 @@ const runVerify = Effect.fn("okfit/verify/runVerify")(function* (options) {
 		at,
 		priorAt: prepared.priorAt,
 		dryRun: options.dryRun,
-		fragment: prepared.fragment
+		fragment: prepared.fragment,
+		status: options.status === void 0 ? null : {
+			from: concept.frontmatter.status ?? null,
+			to: options.status
+		},
+		statusFragment: prepared.statusFragment
 	};
 });
 /**
 * Issue #138. Attests every concept selected by `options.types` (or, when
 * empty, every type whose declaration sets `require_verified = true`) that
-* is not a draft and does not already carry a `verified` entry by the
+* is not a draft, is not deprecated (#143) and does not already carry a `verified` entry by the
 * resolved actor. Every candidate is located FIRST -- an unsupported
 * `verified` shape on any one of them fails the whole batch with nothing
 * written, mirroring `runVerify`'s own fail-closed rule at batch scale.
@@ -124,43 +153,66 @@ const runVerify = Effect.fn("okfit/verify/runVerify")(function* (options) {
 */
 const runVerifyBatch = Effect.fn("okfit/verify/runVerifyBatch")(function* (options) {
 	const bundle = yield* Bundle.load({ root: options.bundleRoot });
-	const declared = options.config.types ?? {};
-	let types;
-	if (options.types.length > 0) {
-		for (const type of options.types) if (!Object.hasOwn(declared, type)) return yield* new VerifySelectionError({
-			reason: "unknown-type",
-			detail: type
-		});
-		types = new Set(options.types);
-	} else types = new Set(Object.entries(declared).flatMap(([name, spec]) => spec.require_verified === true ? [name] : []));
+	const types = yield* resolveBatchTypes(options.config, options.types);
+	const actor = yield* Derivation.generatedBy({
+		writer: "human",
+		cwd: options.projectRoot,
+		config: options.config
+	});
+	const at = Schema.encodeSync(Timestamp)(options.at);
+	const selection = selectAttestable(bundle, types, actor);
+	const prepared = [];
+	for (const concept of selection.candidates) prepared.push({
+		id: concept.id,
+		conceptPath: concept.path,
+		...yield* prepareVerify(bundle, concept, actor, at, void 0)
+	});
+	if (!options.dryRun) for (const entry of prepared) yield* writeVerified(entry.absolutePath, entry.finalText);
+	return {
+		bundleRoot: bundle.root,
+		by: actor,
+		at,
+		dryRun: options.dryRun,
+		verified: prepared.map(({ id, conceptPath, fragment }) => ({
+			id,
+			conceptPath,
+			fragment
+		})),
+		skipped: selection.skipped
+	};
+});
+/**
+* Issue #214. Attests an explicit list of concept ids in one all-or-nothing
+* batch. Every id is resolved exactly as {@link runVerify} resolves it, and
+* every concept is located and spliced BEFORE any file is written, so one
+* unknown id, reserved file or unsupported `verified`/`status` shape fails the
+* whole call with the tree untouched. An explicit pick is never second-guessed:
+* drafts, deprecated and already-attested concepts are all attested, and
+* `skipped` is always empty. Duplicate ids (after normalisation) are written
+* once. With `promote`, a draft's `status` becomes `stable` in the same write.
+*
+* @public
+*/
+const runVerifyIds = Effect.fn("okfit/verify/runVerifyIds")(function* (options) {
+	const bundle = yield* Bundle.load({ root: options.bundleRoot });
 	const actor = yield* Derivation.generatedBy({
 		writer: "human",
 		cwd: options.projectRoot,
 		config: options.config
 	});
 	const at = Schema.encodeSync(Timestamp)(options.at);
-	const skipped = [];
+	const concepts = /* @__PURE__ */ new Map();
+	for (const rawId of options.ids) {
+		const { id, concept } = yield* resolveConcept(bundle, rawId);
+		concepts.set(id, concept);
+	}
 	const prepared = [];
-	for (const [id, concept] of bundle.concepts) {
-		if (!types.has(concept.frontmatter.type)) continue;
-		if (concept.frontmatter.status === "draft") {
-			skipped.push({
-				id,
-				reason: "draft"
-			});
-			continue;
-		}
-		if ((concept.frontmatter.verified ?? []).some((entry) => entry.by === actor)) {
-			skipped.push({
-				id,
-				reason: "already-verified"
-			});
-			continue;
-		}
+	for (const [id, concept] of concepts) {
+		const status = options.promote === true && concept.frontmatter.status === "draft" ? "stable" : void 0;
 		prepared.push({
 			id,
 			conceptPath: concept.path,
-			...yield* prepareVerify(bundle, concept, actor, at)
+			...yield* prepareVerify(bundle, concept, actor, at, status)
 		});
 	}
 	if (!options.dryRun) for (const entry of prepared) yield* writeVerified(entry.absolutePath, entry.finalText);
@@ -174,9 +226,28 @@ const runVerifyBatch = Effect.fn("okfit/verify/runVerifyBatch")(function* (optio
 			conceptPath,
 			fragment
 		})),
-		skipped
+		skipped: []
+	};
+});
+/**
+* The interactive verify picker's starting point: loads the bundle, resolves
+* the human actor from git exactly as {@link runVerify} does, and selects the
+* rows that actor may still attest. Reads only; nothing is written.
+*
+* @public
+*/
+const loadPickerCandidates = Effect.fn("okfit/verify/loadPickerCandidates")(function* (options) {
+	const bundle = yield* Bundle.load({ root: options.bundleRoot });
+	const by = yield* Derivation.generatedBy({
+		writer: "human",
+		cwd: options.projectRoot,
+		config: options.config
+	});
+	return {
+		by,
+		candidates: selectPickerCandidates(bundle, options.config, by)
 	};
 });
 
 //#endregion
-export { runVerify, runVerifyBatch };
+export { loadPickerCandidates, runVerify, runVerifyBatch, runVerifyIds };