@okfit/engine 0.10.0 → 0.11.0

package/errors.js

@@ -137,7 +137,7 @@ var VerifySelectionError = class extends Schema.TaggedError()("VerifySelectionEr
 }) {
 	[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";

package/index.d.ts

@@ -1577,6 +1577,30 @@ interface AttestableSelection {
  * @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
@@ -2035,6 +2059,67 @@ export declare const runVerifyBatch: (options: VerifyBatchOptions) => Effect.Eff
     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
 /**
@@ -2051,5 +2136,5 @@ export declare const runVerifyBatch: (options: VerifyBatchOptions) => Effect.Eff
  */
 export declare const ENGINE_VERSION: string;
 //#endregion
-export type { AttestableSelection, BundleSessionOptions, BundleSessionServices, BundleSessionShape, ConceptFilter, ConceptLink, ConceptNeighbor, 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

package/index.js

@@ -28,7 +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 { resolveBatchTypes, selectAttestable } from "./verify/select.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, 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, makeOverlayFileSystem, provideConfig, provideDocuments, queryGetEnvelope, queryListEnvelope, queryNeighborsEnvelope, resolveBatchTypes, resolveBundleRoot, resolveDocumentPath, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, runVerifyBatch, selectAttestable, sort, staleEnvelope, syncEnvelope, tally, targetPaths, toConceptSummary, 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.10.0",
+	"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.1",
-		"@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.1",
-		"@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/verify/run.js

@@ -1,7 +1,7 @@
 import { VerifyConceptNotFoundError, VerifyUnsupportedFrontmatterError } from "../errors.js";
 import { documentNewline, locate, locateTopLevelScalar, stripBom } from "./locate.js";
 import { mergeSameOffset, splice, spliceTopLevelScalar } from "./splice.js";
-import { resolveBatchTypes, selectAttestable } from "./select.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";
@@ -71,22 +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 `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 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"
 	});
@@ -109,6 +98,25 @@ 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,
@@ -173,6 +181,73 @@ const runVerifyBatch = Effect.fn("okfit/verify/runVerifyBatch")(function* (optio
 		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 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 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, status)
+		});
+	}
+	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: []
+	};
+});
+/**
+* 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 };

package/verify/select.js

@@ -36,6 +36,33 @@ const selectAttestable = (bundle, types, actor) => {
 		skipped
 	};
 };
+const requireVerifiedTypes = (config) => new Set(Object.entries(config.types ?? {}).flatMap(([name, spec]) => spec.require_verified === true ? [name] : []));
+/**
+* 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
+*/
+const selectPickerCandidates = (bundle, config, actor) => {
+	const types = requireVerifiedTypes(config);
+	const rows = [];
+	for (const [id, concept] of bundle.concepts) {
+		const { type, status, title, description } = concept.frontmatter;
+		if (!types.has(type) || status === "deprecated") continue;
+		const verified = concept.frontmatter.verified ?? [];
+		if (verified.some((entry) => entry.by === actor)) continue;
+		rows.push({
+			id,
+			type,
+			status: status === "draft" ? "draft" : "stable",
+			title: title ?? null,
+			description: description ?? null,
+			otherAttestations: verified.length
+		});
+	}
+	return rows.toSorted((a, b) => a.type < b.type ? -1 : a.type > b.type ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+};
 /**
 * The batch type-resolution rule shared by `runVerifyBatch` and any future
 * interactive picker: explicit `types` must each be declared in
@@ -47,7 +74,7 @@ const selectAttestable = (bundle, types, actor) => {
 */
 const resolveBatchTypes = (config, types) => {
 	const declared = config.types ?? {};
-	if (types.length === 0) return Effect.succeed(new Set(Object.entries(declared).flatMap(([name, spec]) => spec.require_verified === true ? [name] : [])));
+	if (types.length === 0) return Effect.succeed(requireVerifiedTypes(config));
 	for (const type of types) if (!Object.hasOwn(declared, type)) return Effect.fail(new VerifySelectionError({
 		reason: "unknown-type",
 		detail: type
@@ -56,4 +83,4 @@ const resolveBatchTypes = (config, types) => {
 };
 
 //#endregion
-export { resolveBatchTypes, selectAttestable };
+export { resolveBatchTypes, selectAttestable, selectPickerCandidates };

package/version.js

@@ -11,7 +11,7 @@
 *
 * @public
 */
-const ENGINE_VERSION = "0.10.0";
+const ENGINE_VERSION = "0.11.0";
 
 //#endregion
 export { ENGINE_VERSION };