@okfit/engine 0.9.4 → 0.11.0

package/errors.js

@@ -60,7 +60,8 @@ var VerifyConceptNotFoundError = class extends Schema.TaggedError()("VerifyConce
 	}
 };
 /**
-* V-14: fail closed on a `verified` shape the classifier does not name.
+* V-14: fail closed on a `verified` (or, under `--stable`/`--draft`, `status`)
+* shape the classifier does not name; `key` says which, omitted meaning `verified`.
 * `shape` is one of `"alias"`, `"merge-key"`, `"scalar"`, `"empty"` (and,
 * defensively, `"no-frontmatter"` or `"not-a-mapping"`, neither reachable
 * for a concept that reached `bundle.concepts`). The file is never opened
@@ -70,11 +71,12 @@ var VerifyConceptNotFoundError = class extends Schema.TaggedError()("VerifyConce
 */
 var VerifyUnsupportedFrontmatterError = class extends Schema.TaggedError()("VerifyUnsupportedFrontmatterError", {
 	id: Schema.String,
-	shape: Schema.String
+	shape: Schema.String,
+	key: Schema.optionalKey(Schema.Literals(["verified", "status"]))
 }) {
 	[Runtime.errorExitCode] = 3;
 	get message() {
-		return `"${this.id}"'s verified value is a shape okfit verify cannot edit (${this.shape}); edit it by hand`;
+		return `"${this.id}"'s ${this.key ?? "verified"} value is a shape okfit verify cannot edit (${this.shape}); edit it by hand`;
 	}
 };
 /** The error's `message` when it has one as a string, else `String(error)`. */
@@ -127,14 +129,18 @@ var VerifySelectionError = class extends Schema.TaggedError()("VerifySelectionEr
 	reason: Schema.Literals([
 		"no-selection",
 		"id-and-batch",
-		"unknown-type"
+		"unknown-type",
+		"status-conflict",
+		"status-and-batch"
 	]),
 	detail: Schema.optionalKey(Schema.String)
 }) {
 	[Runtime.errorExitCode] = 64;
 	get message() {
-		if (this.reason === "no-selection") return "verify needs a concept id, --all, or --type <Type>";
+		if (this.reason === "no-selection") return "verify needs a concept id, --all, or --type <Type> (run in a terminal to pick interactively)";
 		if (this.reason === "id-and-batch") return "verify takes either a concept id or --all/--type, not both";
+		if (this.reason === "status-conflict") return "verify takes --stable or --draft, not both";
+		if (this.reason === "status-and-batch") return "--stable and --draft need a concept id; batch mode never changes status";
 		return `type "${this.detail ?? ""}" is not declared in the config`;
 	}
 };
@@ -170,6 +176,50 @@ var DocumentPathError = class extends Schema.TaggedError()("DocumentPathError",
 		return `document path "${this.path}" ${DOCUMENT_PATH_REASON_TEXT[this.reason]}`;
 	}
 };
+/**
+* `okfit query list` named a type or tag the config does not declare. `valid`
+* is the sorted declared names. Exit 64: a usage error.
+*
+* @public
+*/
+var QueryUnknownVocabularyError = class extends Schema.TaggedError()("QueryUnknownVocabularyError", {
+	kind: Schema.Literals(["type", "tag"]),
+	requested: Schema.String,
+	valid: Schema.Array(Schema.String)
+}) {
+	[Runtime.errorExitCode] = 64;
+	get message() {
+		return `${this.kind} "${this.requested}" is not declared in the config; declared: ${this.valid.join(", ")}`;
+	}
+};
+/**
+* A query's concept id named no concept: empty after normalisation
+* (`empty-id`) or absent from the bundle (`not-a-concept`). Exit 3.
+*
+* @public
+*/
+var QueryConceptNotFoundError = class extends Schema.TaggedError()("QueryConceptNotFoundError", {
+	id: Schema.String,
+	reason: Schema.Literals(["empty-id", "not-a-concept"])
+}) {
+	[Runtime.errorExitCode] = 3;
+	get message() {
+		if (this.reason === "empty-id") return "a concept id must not be empty";
+		return `no concept "${this.id}" in this bundle`;
+	}
+};
+/**
+* `okfit query list` was given contradictory selection flags. Exit 64: a
+* usage error.
+*
+* @public
+*/
+var QuerySelectionError = class extends Schema.TaggedError()("QuerySelectionError", { reason: Schema.Literals(["verified-conflict"]) }) {
+	[Runtime.errorExitCode] = 64;
+	get message() {
+		return "query list takes --verified or --unverified, not both";
+	}
+};
 
 //#endregion
-export { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError };
+export { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, QueryConceptNotFoundError, QuerySelectionError, QueryUnknownVocabularyError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError };

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Actor, BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, GraphLink, GraphNode, LinkGraph, LoadedBundle, LoadedConcept, OkfitConfig, OkfitConfigFile, StaleConcept, Status, ValidationReport } from "@okfit/core";
+import { Actor, BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, GraphLink, GraphNode, GraphNodeKind, LinkGraph, LoadedBundle, LoadedConcept, OkfitConfig, OkfitConfigFile, StaleConcept, Status, ValidationReport } from "@okfit/core";
 import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Result, Runtime, Schema } from "effect";
 import { AppDirs, Xdg } from "@effected/xdg";
 import { ConfigReadError } from "@effected/config-file";
@@ -126,9 +126,11 @@ export declare class VerifyConceptNotFoundError extends VerifyConceptNotFoundErr
 declare const VerifyUnsupportedFrontmatterError_base: Schema.Class<VerifyUnsupportedFrontmatterError, Schema.TaggedStruct<"VerifyUnsupportedFrontmatterError", {
   readonly id: Schema.String;
   readonly shape: Schema.String;
+  readonly key: Schema.optionalKey<Schema.Literals<readonly ["verified", "status"]>>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * V-14: fail closed on a `verified` shape the classifier does not name.
+ * V-14: fail closed on a `verified` (or, under `--stable`/`--draft`, `status`)
+ * shape the classifier does not name; `key` says which, omitted meaning `verified`.
  * `shape` is one of `"alias"`, `"merge-key"`, `"scalar"`, `"empty"` (and,
  * defensively, `"no-frontmatter"` or `"not-a-mapping"`, neither reachable
  * for a concept that reached `bundle.concepts`). The file is never opened
@@ -172,7 +174,7 @@ export declare class SyncStagedLogError extends SyncStagedLogError_base {
   get message(): string;
 }
 declare const VerifySelectionError_base: Schema.Class<VerifySelectionError, Schema.TaggedStruct<"VerifySelectionError", {
-  readonly reason: Schema.Literals<readonly ["no-selection", "id-and-batch", "unknown-type"]>;
+  readonly reason: Schema.Literals<readonly ["no-selection", "id-and-batch", "unknown-type", "status-conflict", "status-and-batch"]>;
   readonly detail: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
@@ -202,6 +204,48 @@ export declare class DocumentPathError extends DocumentPathError_base {
   readonly [Runtime.errorExitCode] = 64;
   get message(): string;
 }
+declare const QueryUnknownVocabularyError_base: Schema.Class<QueryUnknownVocabularyError, Schema.TaggedStruct<"QueryUnknownVocabularyError", {
+  readonly kind: Schema.Literals<readonly ["type", "tag"]>;
+  readonly requested: Schema.String;
+  readonly valid: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `okfit query list` named a type or tag the config does not declare. `valid`
+ * is the sorted declared names. Exit 64: a usage error.
+ *
+ * @public
+ */
+export declare class QueryUnknownVocabularyError extends QueryUnknownVocabularyError_base {
+  readonly [Runtime.errorExitCode] = 64;
+  get message(): string;
+}
+declare const QueryConceptNotFoundError_base: Schema.Class<QueryConceptNotFoundError, Schema.TaggedStruct<"QueryConceptNotFoundError", {
+  readonly id: Schema.String;
+  readonly reason: Schema.Literals<readonly ["empty-id", "not-a-concept"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A query's concept id named no concept: empty after normalisation
+ * (`empty-id`) or absent from the bundle (`not-a-concept`). Exit 3.
+ *
+ * @public
+ */
+export declare class QueryConceptNotFoundError extends QueryConceptNotFoundError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const QuerySelectionError_base: Schema.Class<QuerySelectionError, Schema.TaggedStruct<"QuerySelectionError", {
+  readonly reason: Schema.Literals<readonly ["verified-conflict"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `okfit query list` was given contradictory selection flags. Exit 64: a
+ * usage error.
+ *
+ * @public
+ */
+export declare class QuerySelectionError extends QuerySelectionError_base {
+  readonly [Runtime.errorExitCode] = 64;
+  get message(): string;
+}
 //#endregion
 //#region src/config/layer.d.ts
 /**
@@ -652,6 +696,58 @@ export declare const layerOverlayFileSystem: Layer.Layer<FileSystem.FileSystem,
  */
 export declare const OkfitPlatform: Layer.Layer<AppDirs | Xdg | NodeServices.NodeServices, import("@effected/xdg").XdgEnvError, never>;
 //#endregion
+//#region src/query/ConceptQuery.d.ts
+/**
+ * Filter for {@link ConceptQuery.list}. Every field is optional; an absent
+ * field does not constrain.
+ *
+ * @public
+ */
+interface ConceptFilter {
+  /** OR across types. */
+  readonly types?: ReadonlyArray<string>;
+  /** AND: every tag must be present. */
+  readonly tags?: ReadonlyArray<string>;
+  /** OR, compared against `Derive.status` (an absent status reads as stable). */
+  readonly statuses?: ReadonlyArray<Status>;
+  /** `true`: at least one verified entry; `false`: none. */
+  readonly verified?: boolean;
+}
+/** One outgoing link of a concept. @public */
+interface ConceptLink {
+  readonly to: string;
+  readonly kind: GraphNodeKind;
+  readonly source: "body" | "frontmatter";
+  readonly field?: string;
+}
+/** One graph neighbour; `concept` is `null` for a non-concept node (J-4). @public */
+interface ConceptNeighbor {
+  readonly id: string;
+  readonly kind: GraphNodeKind;
+  readonly concept: LoadedConcept | null;
+}
+/**
+ * Read-only queries over a loaded bundle, shared by `okfit query` and the MCP
+ * tools.
+ *
+ * @public
+ */
+export declare const ConceptQuery: {
+  /** Validates types then tags against config (first unknown fails), then filters and sorts by id. */
+  readonly list: (bundle: LoadedBundle, config: OkfitConfig, filter: ConceptFilter) => Effect.Effect<ReadonlyArray<LoadedConcept>, QueryUnknownVocabularyError>;
+  /** One concept by tolerant id, with its outgoing links. */
+  readonly get: (bundle: LoadedBundle, id: string) => Effect.Effect<{
+    readonly concept: LoadedConcept;
+    readonly links: ReadonlyArray<ConceptLink>;
+  }, QueryConceptNotFoundError>;
+  /** Outgoing and incoming graph neighbours of one concept. */
+  readonly neighbors: (bundle: LoadedBundle, id: string) => Effect.Effect<{
+    readonly id: string;
+    readonly outgoing: ReadonlyArray<ConceptNeighbor>;
+    readonly incoming: ReadonlyArray<ConceptNeighbor>;
+  }, QueryConceptNotFoundError>;
+};
+//#endregion
 //#region src/render/context.d.ts
 /** One enumerated value of a `fields[]` entry. @public */
 export declare const ContextFieldValue: Schema.Struct<{
@@ -1088,6 +1184,159 @@ export declare const json: (input: {
 /** K-22. `tag` is the error's `_tag` when it has one, else its constructor name. @public */
 export declare const jsonError: (error: unknown, okfitVersion: string, distribution?: Distribution) => JsonErrorEnvelope;
 //#endregion
+//#region src/render/query.d.ts
+/** The seven-field shape every list-like query result carries (N-16). @public */
+export declare const ConceptSummary: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly type: Schema.String;
+  readonly title: Schema.String;
+  readonly description: Schema.NullOr<Schema.String>;
+  readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+  readonly tags: Schema.$Array<Schema.String>;
+  readonly path: Schema.String;
+}>;
+/** @public */
+export type ConceptSummary = typeof ConceptSummary.Type;
+/** Project one loaded concept into its summary. @public */
+export declare const toConceptSummary: (concept: LoadedConcept) => ConceptSummary;
+/** `okfit query list --format json`'s envelope, schema 1, snake_case. @public */
+export declare const QueryListEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly engine_version: Schema.String;
+  readonly distribution: Schema.NullOr<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly version: Schema.String;
+  }>>;
+  readonly total: Schema.Int;
+  readonly items: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly type: Schema.String;
+    readonly title: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly path: Schema.String;
+  }>>;
+}>;
+/** @public */
+export type QueryListEnvelope = typeof QueryListEnvelope.Type;
+/** One outgoing link of a concept, as `okfit query get` reports it. @public */
+export declare const QueryLink: Schema.Struct<{
+  readonly to: Schema.String;
+  readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+  readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
+  readonly field: Schema.optionalKey<Schema.String>;
+}>;
+/** @public */
+export type QueryLink = typeof QueryLink.Type;
+/** `okfit query get --format json`'s envelope, schema 1, snake_case. @public */
+export declare const QueryGetEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly engine_version: Schema.String;
+  readonly distribution: Schema.NullOr<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly version: Schema.String;
+  }>>;
+  readonly concept: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly type: Schema.String;
+    readonly title: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly path: Schema.String;
+    readonly frontmatter: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly links: Schema.$Array<Schema.Struct<{
+      readonly to: Schema.String;
+      readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+      readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
+      readonly field: Schema.optionalKey<Schema.String>;
+    }>>;
+  }>;
+}>;
+/** @public */
+export type QueryGetEnvelope = typeof QueryGetEnvelope.Type;
+/** One neighbour of a concept; `summary` is `null` for a non-concept node. @public */
+export declare const QueryNeighbor: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+  readonly summary: Schema.NullOr<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly type: Schema.String;
+    readonly title: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly path: Schema.String;
+  }>>;
+}>;
+/** @public */
+export type QueryNeighbor = typeof QueryNeighbor.Type;
+/** `okfit query neighbors --format json`'s envelope, schema 1, snake_case. @public */
+export declare const QueryNeighborsEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly engine_version: Schema.String;
+  readonly distribution: Schema.NullOr<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly version: Schema.String;
+  }>>;
+  readonly id: Schema.String;
+  readonly outgoing: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+    readonly summary: Schema.NullOr<Schema.Struct<{
+      readonly id: Schema.String;
+      readonly type: Schema.String;
+      readonly title: Schema.String;
+      readonly description: Schema.NullOr<Schema.String>;
+      readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+      readonly tags: Schema.$Array<Schema.String>;
+      readonly path: Schema.String;
+    }>>;
+  }>>;
+  readonly incoming: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+    readonly summary: Schema.NullOr<Schema.Struct<{
+      readonly id: Schema.String;
+      readonly type: Schema.String;
+      readonly title: Schema.String;
+      readonly description: Schema.NullOr<Schema.String>;
+      readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+      readonly tags: Schema.$Array<Schema.String>;
+      readonly path: Schema.String;
+    }>>;
+  }>>;
+}>;
+/** @public */
+export type QueryNeighborsEnvelope = typeof QueryNeighborsEnvelope.Type;
+/** Build the list envelope; `items` is the already-paged, already-sorted summaries. @public */
+export declare const queryListEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly total: number;
+  readonly items: ReadonlyArray<ConceptSummary>;
+  readonly distribution?: Distribution;
+}) => QueryListEnvelope;
+/** Build the get envelope from a summary, the raw frontmatter and the outgoing links. @public */
+export declare const queryGetEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly concept: ConceptSummary;
+  readonly frontmatter: Readonly<Record<string, unknown>>;
+  readonly links: ReadonlyArray<QueryLink>;
+  readonly distribution?: Distribution;
+}) => QueryGetEnvelope;
+/** Build the neighbors envelope. @public */
+export declare const queryNeighborsEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly id: string;
+  readonly outgoing: ReadonlyArray<QueryNeighbor>;
+  readonly incoming: ReadonlyArray<QueryNeighbor>;
+  readonly distribution?: Distribution;
+}) => QueryNeighborsEnvelope;
+//#endregion
 //#region src/render/stale.d.ts
 /** One entry of the `items` array. @public */
 export declare const StaleItem: Schema.Struct<{
@@ -1298,6 +1547,71 @@ export declare const syncEnvelope: (input: {
   readonly distribution?: Distribution;
 }) => SyncEnvelope;
 //#endregion
+//#region src/verify/select.d.ts
+/**
+ * Why a candidate concept was skipped by batch selection: `"draft"` and
+ * `"deprecated"` mirror `status`, `"already-verified"` means the actor already
+ * carries a `verified` entry.
+ *
+ * @public
+ */
+type VerifyBatchSkipReason = "draft" | "deprecated" | "already-verified";
+/**
+ * The outcome of {@link selectAttestable}.
+ *
+ * @public
+ */
+interface AttestableSelection {
+  /** In bundle iteration order. */
+  readonly candidates: ReadonlyArray<LoadedConcept>;
+  readonly skipped: ReadonlyArray<{
+    readonly id: string;
+    readonly reason: VerifyBatchSkipReason;
+  }>;
+}
+/**
+ * Issue #138/#143: which concepts of `types` the actor may attest in one
+ * batch. A draft is unsettled and a deprecated concept is retired (#143), so
+ * both are skipped before the already-verified check.
+ *
+ * @public
+ */
+export declare const selectAttestable: (bundle: LoadedBundle, types: ReadonlySet<string>, actor: string) => AttestableSelection;
+/**
+ * One row of the interactive verify picker: a `require_verified` concept the
+ * actor has not attested yet.
+ *
+ * @public
+ */
+interface PickerCandidate {
+  readonly id: string;
+  readonly type: string;
+  /** `"stable"` when the concept carries no `status`. */
+  readonly status: "draft" | "stable";
+  readonly title: string | null;
+  readonly description: string | null;
+  /** How many `verified` entries by actors other than the current one. */
+  readonly otherAttestations: number;
+}
+/**
+ * Every concept whose type sets `require_verified` that `actor` has not
+ * attested: drafts included, deprecated concepts and the actor's own
+ * attestations excluded. Sorted by type, then id; grouping is the caller's.
+ *
+ * @public
+ */
+export declare const selectPickerCandidates: (bundle: LoadedBundle, config: OkfitConfig, actor: string) => ReadonlyArray<PickerCandidate>;
+/**
+ * The batch type-resolution rule shared by `runVerifyBatch` and any future
+ * interactive picker: explicit `types` must each be declared in
+ * `config.types` (else `VerifySelectionError` with reason `unknown-type`);
+ * an empty `types` selects every declared type whose `require_verified` is
+ * `true`.
+ *
+ * @public
+ */
+export declare const resolveBatchTypes: (config: OkfitConfig, types: ReadonlyArray<string>) => Effect.Effect<ReadonlySet<string>, VerifySelectionError>;
+//#endregion
 //#region src/render/verify.d.ts
 /**
  * V-11's success envelope, schema 1, snake_case — the same convention as
@@ -1322,6 +1636,11 @@ export declare const VerifyEnvelope: Schema.Struct<{
     readonly by: Schema.String;
     readonly at: Schema.String;
   }>;
+  /** Issue #185: the status change `--stable`/`--draft` made; `null` when neither flag was given. */
+  readonly status: Schema.NullOr<Schema.Struct<{
+    readonly from: Schema.NullOr<Schema.Literals<readonly ["draft", "stable", "deprecated"]>>;
+    readonly to: Schema.Literals<readonly ["stable", "draft"]>;
+  }>>;
   readonly dry_run: Schema.Boolean;
   readonly exit_code: Schema.Literal<0>;
 }>;
@@ -1342,6 +1661,10 @@ export declare const verifyEnvelope: (input: {
   readonly by: string;
   readonly at: string;
   readonly dryRun: boolean;
+  readonly status: {
+    readonly from: Status | null;
+    readonly to: "stable" | "draft";
+  } | null;
   readonly distribution?: Distribution;
 }) => VerifyEnvelope;
 /**
@@ -1368,7 +1691,7 @@ export declare const VerifyBatchEnvelope: Schema.Struct<{
   }>>;
   readonly skipped: Schema.$Array<Schema.Struct<{
     readonly id: Schema.String;
-    readonly reason: Schema.Literals<readonly ["draft", "already-verified"]>;
+    readonly reason: Schema.Literals<readonly ["draft", "deprecated", "already-verified"]>;
   }>>;
   readonly dry_run: Schema.Boolean;
   readonly exit_code: Schema.Literal<0>;
@@ -1391,7 +1714,7 @@ export declare const verifyBatchEnvelope: (input: {
   }>;
   readonly skipped: ReadonlyArray<{
     readonly id: string;
-    readonly reason: "draft" | "already-verified";
+    readonly reason: VerifyBatchSkipReason;
   }>;
   readonly dryRun: boolean;
   readonly distribution?: Distribution;
@@ -1621,6 +1944,8 @@ interface VerifyOptions {
   /** `--at` when given, else the `Now` service (K-47/K-49). */
   readonly at: DateTime.Utc;
   readonly dryRun: boolean;
+  /** Issue #185: also set the concept's `status` in the same write. */
+  readonly status?: "stable" | "draft";
 }
 /** @internal */
 interface VerifyResult {
@@ -1638,6 +1963,13 @@ interface VerifyResult {
   readonly dryRun: boolean;
   /** The exact bytes `splice`'s edit would insert, written or not. */
   readonly fragment: string;
+  /** `null` when no status flag was given; `from` is the RAW frontmatter status. */
+  readonly status: {
+    readonly from: Status | null;
+    readonly to: "stable" | "draft";
+  } | null;
+  /** The exact status bytes spliced, or `null` when no status edit was made. */
+  readonly statusFragment: string | null;
 }
 /**
  * Issue #138: options for {@link runVerifyBatch}. `types` restricts the
@@ -1655,14 +1987,6 @@ interface VerifyBatchOptions {
   /** Restrict to these types; empty = every type with `require_verified = true`. */
   readonly types: ReadonlyArray<string>;
 }
-/**
- * Why {@link runVerifyBatch} skipped a candidate concept: `"draft"` for
- * `status === "draft"`, `"already-verified"` when the resolved actor already
- * carries a `verified` entry.
- *
- * @public
- */
-type VerifyBatchSkipReason = "draft" | "already-verified";
 /**
  * The result of {@link runVerifyBatch}.
  *
@@ -1689,8 +2013,9 @@ interface VerifyBatchResult {
  * 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).
+ * 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
  */
@@ -1703,11 +2028,16 @@ export declare const runVerify: (options: VerifyOptions) => Effect.Effect<{
   priorAt: string[];
   dryRun: boolean;
   fragment: string;
+  status: {
+    from: "deprecated" | "draft" | "stable" | null;
+    to: "draft" | "stable";
+  } | null;
+  statusFragment: string | null;
 }, import("effect/PlatformError").PlatformError | VerifyConceptNotFoundError | VerifyUnsupportedFrontmatterError | import("@effected/yaml").YamlParseError | import("@okfit/core").BundleLoadError | import("@okfit/profiles").GeneratedByError, FileSystem.FileSystem | import("@effected/git").Git | Path.Path>;
 /**
  * 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.
@@ -1724,11 +2054,72 @@ export declare const runVerifyBatch: (options: VerifyBatchOptions) => Effect.Eff
     conceptPath: string;
     fragment: string;
   }[];
-  skipped: {
+  skipped: readonly {
     readonly id: string;
     readonly reason: VerifyBatchSkipReason;
   }[];
 }, import("effect/PlatformError").PlatformError | VerifySelectionError | VerifyUnsupportedFrontmatterError | import("@effected/yaml").YamlParseError | import("@okfit/core").BundleLoadError | import("@okfit/profiles").GeneratedByError, FileSystem.FileSystem | import("@effected/git").Git | Path.Path>;
+/**
+ * Issue #214: options for {@link runVerifyIds}.
+ *
+ * @public
+ */
+interface VerifyIdsOptions {
+  readonly bundleRoot: string;
+  readonly projectRoot: string;
+  readonly config: OkfitConfig;
+  readonly at: DateTime.Utc;
+  readonly dryRun: boolean;
+  /** Concept ids, resolved as `runVerify` resolves one (tolerant: leading slash, trailing `.md`). */
+  readonly ids: ReadonlyArray<string>;
+  /** Also set `status: stable` on every selected concept whose status is `draft`. Default `false`. */
+  readonly promote?: boolean;
+}
+/**
+ * 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
+ */
+export declare const runVerifyIds: (options: VerifyIdsOptions) => Effect.Effect<{
+  bundleRoot: string;
+  by: Actor;
+  at: string;
+  dryRun: boolean;
+  verified: {
+    id: string;
+    conceptPath: string;
+    fragment: string;
+  }[];
+  skipped: never[];
+}, import("effect/PlatformError").PlatformError | VerifyConceptNotFoundError | VerifyUnsupportedFrontmatterError | import("@effected/yaml").YamlParseError | import("@okfit/core").BundleLoadError | import("@okfit/profiles").GeneratedByError, FileSystem.FileSystem | import("@effected/git").Git | Path.Path>;
+/**
+ * Options for {@link loadPickerCandidates}.
+ *
+ * @public
+ */
+interface PickerCandidatesOptions {
+  readonly bundleRoot: string;
+  readonly projectRoot: string;
+  readonly config: OkfitConfig;
+}
+/**
+ * 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
+ */
+export declare const loadPickerCandidates: (options: PickerCandidatesOptions) => Effect.Effect<{
+  by: Actor;
+  candidates: readonly PickerCandidate[];
+}, import("@okfit/core").BundleLoadError | import("@okfit/profiles").GeneratedByError, FileSystem.FileSystem | import("@effected/git").Git | Path.Path>;
 //#endregion
 //#region src/version.d.ts
 /**
@@ -1745,5 +2136,5 @@ export declare const runVerifyBatch: (options: VerifyBatchOptions) => Effect.Eff
  */
 export declare const ENGINE_VERSION: string;
 //#endregion
-export type { BundleSessionOptions, BundleSessionServices, BundleSessionShape, ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, Distribution, DocumentInput, ExternalReferencesShape, GraphRunOptions, GraphRunResult, OverlayDocument, OverlayDocumentsShape, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RevalidateError, RevalidateOptions, RevalidateResult, RevalidateTier, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, StaleRunOptions, StaleRunResult, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyBatchOptions, VerifyBatchResult, VerifyBatchSkipReason, VerifyOptions, VerifyResult, WatchedFilesOutcome };
+export type { AttestableSelection, BundleSessionOptions, BundleSessionServices, BundleSessionShape, ConceptFilter, ConceptLink, ConceptNeighbor, ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, Distribution, DocumentInput, ExternalReferencesShape, GraphRunOptions, GraphRunResult, OverlayDocument, OverlayDocumentsShape, PickerCandidate, PickerCandidatesOptions, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RevalidateError, RevalidateOptions, RevalidateResult, RevalidateTier, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, StaleRunOptions, StaleRunResult, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyBatchOptions, VerifyBatchResult, VerifyBatchSkipReason, VerifyIdsOptions, VerifyOptions, VerifyResult, WatchedFilesOutcome };
 //# sourceMappingURL=index.d.ts.map