@okfit/engine 0.7.5 → 0.9.0

package/README.md

@@ -4,6 +4,8 @@ The shared engine behind [okfit](https://github.com/spencerbeggs/okfit): the pla
 
 You probably want `@okfit/plugin` (both bins), `@okfit/cli` (the `okfit` bin) or `@okfit/mcp` (the `okfit-mcp` bin) instead. This package is what they are built from.
 
+`FrontmatterEdits` is a public facade over the `verify` splice machinery: it produces `MarkdownEdit`s for a concept's top-level `status` scalar and its `verified` list, with whole-file offsets into the source as passed (BOM included), so a consumer such as `@okfit/lsp` can apply them directly or map them to editor ranges without adjustment.
+
 ## License
 
 [MIT](LICENSE)

package/edits/FrontmatterEdits.js

@@ -0,0 +1,76 @@
+import { documentNewline, locate, locateTopLevelScalar, stripBom } from "../verify/locate.js";
+import { splice, spliceTopLevelScalar } from "../verify/splice.js";
+import { Effect, Runtime, Schema } from "effect";
+import { MarkdownEdit } from "@effected/markdown";
+
+//#region src/edits/FrontmatterEdits.ts
+/**
+* A top-level frontmatter key `FrontmatterEdits` was asked to edit turned
+* out to be a shape it cannot splice: `shape` is whichever locator string
+* `verify/locate.ts` produced for that key (e.g. `"flow-mapping"`,
+* `"alias"`, `"status-block-scalar"`). The file is never touched when this
+* is raised -- callers should surface it and let a human edit by hand.
+*
+* @public
+*/
+var UnsupportedFrontmatterError = class extends Schema.TaggedError()("UnsupportedFrontmatterError", {
+	key: Schema.String,
+	shape: Schema.String
+}) {
+	[Runtime.errorExitCode] = 3;
+	get message() {
+		return `"${this.key}"'s frontmatter value is a shape FrontmatterEdits cannot edit (${this.shape}); edit it by hand`;
+	}
+};
+/** `edit` shifted forward by `by` bytes, or `edit` itself when `by` is zero. */
+const shift = (edit, by) => by === 0 ? edit : MarkdownEdit.make({
+	offset: edit.offset + by,
+	length: edit.length,
+	content: edit.content
+});
+/**
+* A public facade over the `verify/locate.ts` and `verify/splice.ts`
+* machinery: byte-range `MarkdownEdit`s for a concept's top-level `status`
+* scalar and its `verified` list. `verified` builds the exact same edit
+* `okfit verify`'s `prepareVerify` builds -- same `locate`, same `splice`,
+* same `documentNewline` newline choice -- so its output matches
+* `okfit verify`'s splice byte for byte; `status` reuses the identical
+* newline rule for consistency, over `locateTopLevelScalar` and
+* `spliceTopLevelScalar` instead.
+*
+* Every offset returned is a WHOLE-FILE offset into `source` AS PASSED --
+* BOM included when present -- so a caller can apply the edits with
+* `MarkdownEdit.applyAll(source, edits)` directly, or map them to editor
+* ranges without adjustment. Internally the BOM is stripped for parsing and
+* its length added back to every offset before returning.
+*
+* @public
+*/
+var FrontmatterEdits = class {
+	constructor() {}
+	/** Edits that set top-level `status` to `status`, replacing an existing scalar or inserting after `title:` (else `type:`). */
+	static status = (source, status) => Effect.gen(function* () {
+		const { text, bom } = stripBom(source);
+		const target = yield* locateTopLevelScalar(text, "status");
+		if (target._tag === "unsupported") return yield* new UnsupportedFrontmatterError({
+			key: "status",
+			shape: target.shape
+		});
+		const edit = spliceTopLevelScalar(target, "status", status, documentNewline(text));
+		return [shift(edit, bom.length)];
+	});
+	/** Edits that append one verified entry, the same splice `okfit verify` performs. */
+	static verified = (source, entry) => Effect.gen(function* () {
+		const { text, bom } = stripBom(source);
+		const target = yield* locate(text);
+		if (target._tag === "unsupported") return yield* new UnsupportedFrontmatterError({
+			key: "verified",
+			shape: target.shape
+		});
+		const edit = splice(target, entry, documentNewline(text));
+		return [shift(edit, bom.length)];
+	});
+};
+
+//#endregion
+export { FrontmatterEdits, UnsupportedFrontmatterError };

package/index.d.ts

@@ -1,10 +1,12 @@
-import { Actor, BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, GraphLink, GraphNode, LinkGraph, LoadedBundle, OkfitConfig, OkfitConfigFile, StaleConcept, ValidationReport } from "@okfit/core";
+import { Actor, BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, GraphLink, GraphNode, 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";
 import { GeneratedAtError, GitHistory, GitHistoryError, Layout, Profile, ProfileDiagnostic } from "@okfit/profiles";
-import { FrontmatterWriteError, MarkdownParseError } from "@effected/markdown";
+import { FrontmatterWriteError, MarkdownEdit, MarkdownParseError } from "@effected/markdown";
+import { YamlParseError } from "@effected/yaml";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Distribution as Distribution$1 } from "@effected/engine";
 import { Git, GitCommandError, UnknownRefError } from "@effected/git";
 //#region src/config/anchor.d.ts
 /**
@@ -375,6 +377,53 @@ interface ContextResult {
  */
 export declare const runContext: (options: ContextRunOptions) => Effect.Effect<ContextResult, never, FileSystem.FileSystem | Path.Path>;
 //#endregion
+//#region src/edits/FrontmatterEdits.d.ts
+declare const UnsupportedFrontmatterError_base: Schema.Class<UnsupportedFrontmatterError, Schema.TaggedStruct<"UnsupportedFrontmatterError", {
+  readonly key: Schema.String;
+  readonly shape: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A top-level frontmatter key `FrontmatterEdits` was asked to edit turned
+ * out to be a shape it cannot splice: `shape` is whichever locator string
+ * `verify/locate.ts` produced for that key (e.g. `"flow-mapping"`,
+ * `"alias"`, `"status-block-scalar"`). The file is never touched when this
+ * is raised -- callers should surface it and let a human edit by hand.
+ *
+ * @public
+ */
+export declare class UnsupportedFrontmatterError extends UnsupportedFrontmatterError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+/**
+ * A public facade over the `verify/locate.ts` and `verify/splice.ts`
+ * machinery: byte-range `MarkdownEdit`s for a concept's top-level `status`
+ * scalar and its `verified` list. `verified` builds the exact same edit
+ * `okfit verify`'s `prepareVerify` builds -- same `locate`, same `splice`,
+ * same `documentNewline` newline choice -- so its output matches
+ * `okfit verify`'s splice byte for byte; `status` reuses the identical
+ * newline rule for consistency, over `locateTopLevelScalar` and
+ * `spliceTopLevelScalar` instead.
+ *
+ * Every offset returned is a WHOLE-FILE offset into `source` AS PASSED --
+ * BOM included when present -- so a caller can apply the edits with
+ * `MarkdownEdit.applyAll(source, edits)` directly, or map them to editor
+ * ranges without adjustment. Internally the BOM is stripped for parsing and
+ * its length added back to every offset before returning.
+ *
+ * @public
+ */
+export declare class FrontmatterEdits {
+  private constructor();
+  /** Edits that set top-level `status` to `status`, replacing an existing scalar or inserting after `title:` (else `type:`). */
+  static readonly status: (source: string, status: Status) => Effect.Effect<ReadonlyArray<MarkdownEdit>, YamlParseError | UnsupportedFrontmatterError>;
+  /** Edits that append one verified entry, the same splice `okfit verify` performs. */
+  static readonly verified: (source: string, entry: {
+    readonly by: string;
+    readonly at: string;
+  }) => Effect.Effect<ReadonlyArray<MarkdownEdit>, YamlParseError | UnsupportedFrontmatterError>;
+}
+//#endregion
 //#region src/external/ExternalReferences.d.ts
 /**
  * Reachability of an external reference: `unknown` means never checked.
@@ -756,16 +805,18 @@ export declare const contextEnvelope: (input: {
  * reports; `engine_version` and `okf_version` are the pair a reader
  * compares.
  *
+ * Re-exported from `@effected/engine`'s own `Distribution` -- the shape
+ * both `@okfit/cli`'s `CurrentDistribution` (K-137/carrier-version-threading)
+ * and every JSON envelope in this package agree on, instead of two
+ * independently hand-rolled `{ name, version }` structs drifting apart.
+ *
  * @public
  */
-interface Distribution {
-  readonly name: string;
-  readonly version: string;
-}
+type Distribution = Distribution$1;
 /** Every envelope's `distribution` field: a `Distribution` or `null`. @public */
-export declare const DistributionField: Schema.NullOr<Schema.Struct<{
-  readonly name: Schema.String;
-  readonly version: Schema.String;
+export declare const DistributionField: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
+  readonly name: import("effect/Schema").String;
+  readonly version: import("effect/Schema").String;
 }>>;
 /** @public */
 export type DistributionField = typeof DistributionField.Type;
@@ -1428,6 +1479,20 @@ export declare class BundleSession extends BundleSession_base {
   static readonly make: (options: BundleSessionOptions) => Effect.Effect<BundleSessionShape, never, BundleSessionServices>;
 }
 //#endregion
+//#region src/session/concept.d.ts
+/**
+ * The loaded concept at `absolutePath`, if any. `absolutePath` must already sit under
+ * `bundle.root` (a real resolved path, never re-resolved here: `@okfit/core`'s own
+ * `internal/posixPath.ts` avoids `path.resolve`/`path.relative` on purpose, because both read
+ * `process.cwd()`, and this package holds the same line). Strips `bundle.root` as a plain
+ * string prefix, then applies the same `ConceptId.fromPath` normalisation `withFallbackRange`
+ * uses: `None` for a path outside the bundle, a reserved file (`index.md`, `log.md`), a
+ * non-markdown file, or a markdown file that never decoded into a concept.
+ *
+ * @public
+ */
+export declare const conceptFor: (bundle: LoadedBundle, absolutePath: string) => Option.Option<LoadedConcept>;
+//#endregion
 //#region src/session/range.d.ts
 /**
  * Give a range-less diagnostic somewhere to point (spec 4.3): the concept's

package/index.js

@@ -3,6 +3,7 @@ import { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitO
 import { buildConfigLayer, provideConfig } from "./config/layer.js";
 import { DEFAULT_PROFILE_NAME, resolveProjectConfig } from "./config/resolve.js";
 import { runContext } from "./context/run.js";
+import { FrontmatterEdits, UnsupportedFrontmatterError } from "./edits/FrontmatterEdits.js";
 import { ExternalReferences, ReferenceCheck, ReferenceState } from "./external/ExternalReferences.js";
 import { runGraph } from "./graph/run.js";
 import { CONFIG_RELATIVE_PATH, configValue, files, targetPaths } from "./init/scaffold.js";
@@ -21,9 +22,10 @@ import { SkipReason, runSync } from "./sync/run.js";
 import { SyncEnvelope, SyncModeEnvelope, syncEnvelope } from "./render/sync.js";
 import { VerifyBatchEnvelope, VerifyEnvelope, verifyBatchEnvelope, verifyEnvelope } from "./render/verify.js";
 import { Now, run } from "./validate/run.js";
+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";
 
-export { BundleSession, CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, DistributionField, DocumentPathError, ENGINE_VERSION, ExternalReferences, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, OverlayDocuments, ReferenceCheck, ReferenceState, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, SyncStagedLogError, VerifyBatchEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifySelectionError, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, 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, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/engine",
-	"version": "0.7.5",
+	"version": "0.9.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": [
@@ -37,17 +37,18 @@
 		"@effect/platform-node": "4.0.0-rc.117",
 		"@effected/app": "^0.18.0",
 		"@effected/config-file": "^0.12.0",
+		"@effected/engine": "^0.1.0",
 		"@effected/git": "^0.17.0",
 		"@effected/glob": "^0.8.0",
 		"@effected/jsonc": "^0.13.0",
-		"@effected/markdown": "^0.12.0",
+		"@effected/markdown": "^0.12.1",
 		"@effected/store": "^0.10.0",
 		"@effected/toml": "^0.9.0",
 		"@effected/walker": "^0.12.0",
 		"@effected/xdg": "^0.7.0",
 		"@effected/yaml": "^0.17.0",
-		"@okfit/core": "0.7.4",
-		"@okfit/profiles": "0.7.5",
+		"@okfit/core": "0.8.0",
+		"@okfit/profiles": "0.8.0",
 		"effect": "4.0.0-rc.117"
 	},
 	"engines": {

package/render/distribution.js

@@ -1,11 +1,8 @@
-import { Schema } from "effect";
+import { DistributionField } from "@effected/engine";
 
 //#region src/render/distribution.ts
 /** Every envelope's `distribution` field: a `Distribution` or `null`. @public */
-const DistributionField = Schema.NullOr(Schema.Struct({
-	name: Schema.String,
-	version: Schema.String
-}));
+const DistributionField$1 = DistributionField;
 
 //#endregion
-export { DistributionField };
+export { DistributionField$1 as DistributionField };

package/session/concept.js

@@ -0,0 +1,34 @@
+import { ConceptId } from "@okfit/core";
+import { Option } from "effect";
+
+//#region src/session/concept.ts
+/** Backslashes to forward slashes; the rest of this module treats every path as already resolved. */
+const posixOf = (value) => value.split("\\").join("/");
+/** Drops every trailing `/` without a regex (a `/\/+$/` pattern is quadratic on a long run of slashes). */
+const stripTrailingSlashes = (path) => {
+	let end = path.length;
+	while (end > 0 && path.charCodeAt(end - 1) === 47) end -= 1;
+	return path.slice(0, end);
+};
+/**
+* The loaded concept at `absolutePath`, if any. `absolutePath` must already sit under
+* `bundle.root` (a real resolved path, never re-resolved here: `@okfit/core`'s own
+* `internal/posixPath.ts` avoids `path.resolve`/`path.relative` on purpose, because both read
+* `process.cwd()`, and this package holds the same line). Strips `bundle.root` as a plain
+* string prefix, then applies the same `ConceptId.fromPath` normalisation `withFallbackRange`
+* uses: `None` for a path outside the bundle, a reserved file (`index.md`, `log.md`), a
+* non-markdown file, or a markdown file that never decoded into a concept.
+*
+* @public
+*/
+const conceptFor = (bundle, absolutePath) => {
+	const root = stripTrailingSlashes(posixOf(bundle.root));
+	const target = posixOf(absolutePath);
+	const prefix = `${root}/`;
+	if (!target.startsWith(prefix)) return Option.none();
+	const relative = target.slice(prefix.length);
+	return Option.flatMap(ConceptId.fromPath(relative), (id) => Option.fromUndefinedOr(bundle.concepts.get(id)));
+};
+
+//#endregion
+export { conceptFor };

package/session/range.js

@@ -1,4 +1,5 @@
-import { ConceptId, DiagnosticRange } from "@okfit/core";
+import { conceptFor } from "./concept.js";
+import { DiagnosticRange } from "@okfit/core";
 import { Option } from "effect";
 
 //#region src/session/range.ts
@@ -20,10 +21,7 @@ const FILE_START = DiagnosticRange.make({
 */
 const withFallbackRange = (bundle, diagnostic) => {
 	if (diagnostic.range !== void 0 || diagnostic.file === "") return diagnostic;
-	const concept = Option.match(ConceptId.fromPath(diagnostic.file), {
-		onNone: () => void 0,
-		onSome: (id) => bundle.concepts.get(id)
-	});
+	const concept = Option.getOrUndefined(conceptFor(bundle, `${bundle.root}/${diagnostic.file}`));
 	const node = concept?.document.frontmatter;
 	if (concept === void 0 || node === void 0) return {
 		...diagnostic,

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.1"
+      "packageVersion": "7.59.2"
     }
   ]
 }

package/validate/resources.js

@@ -1,4 +1,4 @@
-import { Diagnostic, OkfitConfig } from "@okfit/core";
+import { Diagnostic, DiagnosticRange, OkfitConfig } from "@okfit/core";
 import { Effect, FileSystem, Path } from "effect";
 
 //#region src/validate/resources.ts
@@ -22,11 +22,23 @@ const stripSuffix = (value) => {
 	const at = value.search(/[?#]/);
 	return at === -1 ? value : value.slice(0, at);
 };
-/** Every `resource` value on a concept: the top-level field, then each source's. */
+/** Every `resource` value on a concept, each with its own frontmatter path: the top-level field, then each source's. */
 const resourceValuesOf = (concept) => {
 	const values = [];
-	if (concept.frontmatter.resource !== void 0) values.push(concept.frontmatter.resource);
-	for (const source of concept.frontmatter.sources ?? []) values.push(source.resource);
+	if (concept.frontmatter.resource !== void 0) values.push({
+		value: concept.frontmatter.resource,
+		path: ["resource"]
+	});
+	concept.frontmatter.sources?.forEach((source, index) => {
+		values.push({
+			value: source.resource,
+			path: [
+				"sources",
+				index,
+				"resource"
+			]
+		});
+	});
 	return values;
 };
 /**
@@ -36,9 +48,11 @@ const resourceValuesOf = (concept) => {
 * pattern) or a literal path resolved in D-23 order: relative to the
 * concept's own directory, then (for a bare path) relative to the bundle
 * root, or with a leading `/` relative to the bundle root only; only the
-* latter is checked against the filesystem. Total over severity (mirrors
-* `Provenance.lint`'s S-28 posture): returns `[]`, touching neither
-* `FileSystem` nor `Path`, the moment
+* latter is checked against the filesystem. Ranges at the offending value
+* (phase 4 decision 2, via `DiagnosticRange.forFrontmatterPath`) using the
+* `["resource"]` or `["sources", index, "resource"]` path the value came
+* from. Total over severity (mirrors `Provenance.lint`'s S-28 posture):
+* returns `[]`, touching neither `FileSystem` nor `Path`, the moment
 * `OkfitConfig.severityFor(config, "source-resource-missing")` is `"off"`.
 *
 * @public
@@ -49,7 +63,7 @@ const lintResources = (bundle, config) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const diagnostics = [];
-	for (const [, concept] of bundle.concepts) for (const value of resourceValuesOf(concept)) {
+	for (const [, concept] of bundle.concepts) for (const { value, path: fieldPath } of resourceValuesOf(concept)) {
 		if (isDescriptor(value)) continue;
 		const stripped = stripSuffix(value);
 		const candidates = stripped.startsWith("/") ? [path.join(bundle.root, stripped.slice(1))] : [path.resolve(bundle.root, path.dirname(concept.path), stripped), ...stripped.startsWith("./") || stripped.startsWith("../") ? [] : [path.resolve(bundle.root, stripped)]];
@@ -59,11 +73,13 @@ const lintResources = (bundle, config) => Effect.gen(function* () {
 			break;
 		}
 		if (exists) continue;
+		const range = DiagnosticRange.forFrontmatterPath(concept.document, fieldPath);
 		diagnostics.push(Diagnostic.make({
 			file: concept.path,
 			code: "source-resource-missing",
 			severity,
-			message: `Resource "${value}" does not exist relative to ${concept.path}`
+			message: `Resource "${value}" does not exist relative to ${concept.path}`,
+			...range === void 0 ? {} : { range }
 		}));
 	}
 	return diagnostics;

package/verify/locate.js

@@ -55,19 +55,16 @@ const hasMergeKey = (node) => {
 	return false;
 };
 /**
-* Split `source`'s frontmatter, parse its value, find the top-level
-* `verified` pair, and classify it (contract §3.1). Fails only when the
-* frontmatter YAML is fatally unparseable — impossible for a concept that
-* reached `bundle.concepts`, but typed rather than assumed.
-*
-* Offset translation is `valueStart = 3 + newline.length` — `"---".length`
-* plus the opening fence's own terminator, taken from `split`'s fidelity
-* field rather than re-derived with `indexOf` (contract §12 note 9). Every
-* whole-file offset below is `valueStart + <yaml offset>`.
+* The shared prologue every locator in this file starts with: split
+* `source`'s frontmatter, parse its value, and confirm the parsed document
+* is a (non-flow) top-level mapping. Returns the same `"no-frontmatter"` /
+* `"not-a-mapping"` `unsupported` shapes each locator returned inline
+* before this helper existed -- callers still name those shapes themselves,
+* this only removes the duplicated parsing steps that produced them.
 *
 * @internal
 */
-const locate = Effect.fn("okfit/verify/locate")(function* (source) {
+const parseTopLevelMapping = Effect.fn("okfit/verify/parseTopLevelMapping")(function* (source) {
 	const block = FrontmatterSource.split(source).frontmatter;
 	if (block === void 0) return {
 		_tag: "unsupported",
@@ -80,6 +77,29 @@ const locate = Effect.fn("okfit/verify/locate")(function* (source) {
 		_tag: "unsupported",
 		shape: "not-a-mapping"
 	};
+	return {
+		value,
+		valueStart,
+		contents
+	};
+});
+/**
+* Split `source`'s frontmatter, parse its value, find the top-level
+* `verified` pair, and classify it (contract §3.1). Fails only when the
+* frontmatter YAML is fatally unparseable — impossible for a concept that
+* reached `bundle.concepts`, but typed rather than assumed.
+*
+* Offset translation is `valueStart = 3 + newline.length` — `"---".length`
+* plus the opening fence's own terminator, taken from `split`'s fidelity
+* field rather than re-derived with `indexOf` (contract §12 note 9). Every
+* whole-file offset below is `valueStart + <yaml offset>`.
+*
+* @internal
+*/
+const locate = Effect.fn("okfit/verify/locate")(function* (source) {
+	const parsed = yield* parseTopLevelMapping(source);
+	if ("_tag" in parsed) return parsed;
+	const { value, valueStart, contents } = parsed;
 	const pair = contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === "verified");
 	if (pair === void 0) return {
 		_tag: "absent",
@@ -158,18 +178,9 @@ const locate = Effect.fn("okfit/verify/locate")(function* (source) {
 * @internal
 */
 const locateGeneratedField = Effect.fn("okfit/verify/locateGeneratedField")(function* (source, field) {
-	const block = FrontmatterSource.split(source).frontmatter;
-	if (block === void 0) return {
-		_tag: "unsupported",
-		shape: "no-frontmatter"
-	};
-	const value = block.value;
-	const valueStart = 3 + (block.newline ?? "\n").length;
-	const contents = (yield* YamlDocument.parse(value)).contents;
-	if (!(contents instanceof YamlMap)) return {
-		_tag: "unsupported",
-		shape: "not-a-mapping"
-	};
+	const parsed = yield* parseTopLevelMapping(source);
+	if ("_tag" in parsed) return parsed;
+	const { value, valueStart, contents } = parsed;
 	const pair = contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === "generated");
 	if (pair === void 0) return {
 		_tag: "unsupported",
@@ -254,20 +265,77 @@ const locateGenerated = (source) => locateGeneratedField(source, "at");
 * @internal
 */
 const locateGeneratedBodySha256 = (source) => locateGeneratedField(source, "body_sha256");
-/** @internal */
-const locateGeneratedBlock = Effect.fn("okfit/verify/locateGeneratedBlock")(function* (source) {
-	const block = FrontmatterSource.split(source).frontmatter;
-	if (block === void 0) return {
+/**
+* Locate a top-level scalar key (`key`) inside a concept's frontmatter,
+* mirroring `locateGeneratedField`'s parsing prologue. Unlike `generated`'s
+* fields, this key is a direct top-level sibling, not nested inside a block
+* mapping, so there is no intermediate `generated:` lookup and no indent to
+* track for the insert case -- `title:`/`type:` anchor the insert instead.
+*
+* @internal
+*/
+const locateTopLevelScalar = Effect.fn("okfit/verify/locateTopLevelScalar")(function* (source, key) {
+	const parsed = yield* parseTopLevelMapping(source);
+	if ("_tag" in parsed) return parsed;
+	const { value, valueStart, contents } = parsed;
+	if (contents.style === "flow") return {
 		_tag: "unsupported",
-		shape: "no-frontmatter"
+		shape: "flow-mapping"
 	};
-	const value = block.value;
-	const valueStart = 3 + (block.newline ?? "\n").length;
-	const contents = (yield* YamlDocument.parse(value)).contents;
-	if (!(contents instanceof YamlMap)) return {
+	const pair = contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === key);
+	if (pair !== void 0) {
+		const node = pair.value;
+		if (node === null) return {
+			_tag: "unsupported",
+			shape: `${key}-empty`
+		};
+		if (node instanceof YamlAlias) return {
+			_tag: "unsupported",
+			shape: "alias"
+		};
+		if (!(node instanceof YamlScalar)) return {
+			_tag: "unsupported",
+			shape: `${key}-not-scalar`
+		};
+		if (node.style === "block-literal" || node.style === "block-folded") return {
+			_tag: "unsupported",
+			shape: `${key}-block-scalar`
+		};
+		return {
+			_tag: "replaceScalar",
+			start: valueStart + node.offset,
+			end: valueStart + node.offset + node.length,
+			quote: node.style
+		};
+	}
+	const findKey = (name) => contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === name);
+	const titlePair = findKey("title");
+	const anchor = titlePair !== void 0 ? {
+		pair: titlePair,
+		afterKey: "title"
+	} : void 0;
+	const typePair = anchor === void 0 ? findKey("type") : void 0;
+	const resolved = anchor ?? (typePair !== void 0 ? {
+		pair: typePair,
+		afterKey: "type"
+	} : void 0);
+	if (resolved === void 0) return {
 		_tag: "unsupported",
-		shape: "not-a-mapping"
+		shape: "no-anchor-key"
+	};
+	const end = resolved.pair.value !== null ? resolved.pair.value.offset + resolved.pair.value.length : resolved.pair.key.offset + resolved.pair.key.length;
+	const nl = value.indexOf("\n", end);
+	return {
+		_tag: "insertAfterKey",
+		insertAt: valueStart + (value[end - 1] === "\n" ? end : nl === -1 ? value.length : nl + 1),
+		afterKey: resolved.afterKey
 	};
+});
+/** @internal */
+const locateGeneratedBlock = Effect.fn("okfit/verify/locateGeneratedBlock")(function* (source) {
+	const parsed = yield* parseTopLevelMapping(source);
+	if ("_tag" in parsed) return parsed;
+	const { value, valueStart, contents } = parsed;
 	if (contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === "generated") !== void 0) return {
 		_tag: "unsupported",
 		shape: "generated-present"
@@ -279,4 +347,4 @@ const locateGeneratedBlock = Effect.fn("okfit/verify/locateGeneratedBlock")(func
 });
 
 //#endregion
-export { detectNewline, documentNewline, indentAt, locate, locateGenerated, locateGeneratedBlock, locateGeneratedBodySha256, stripBom };
+export { detectNewline, documentNewline, indentAt, locate, locateGenerated, locateGeneratedBlock, locateGeneratedBodySha256, locateTopLevelScalar, stripBom };

package/verify/splice.js

@@ -93,6 +93,30 @@ const spliceGeneratedFields = (atTarget, bodySha256Target, encodedAt, bodySha256
 	return [spliceGenerated(atTarget, encodedAt, newline, "at"), spliceGenerated(bodySha256Target, bodySha256, newline, "body_sha256")];
 };
 /**
+* Build the one edit for `target` (a top-level scalar key such as
+* `status`). Never calls a YAML stringifier: the only syntax emitted is
+* `<key>: `, the preserved quote character (if any), and `newline`.
+*
+* @internal
+*/
+const spliceTopLevelScalar = (target, key, value, newline) => {
+	switch (target._tag) {
+		case "insertAfterKey": return MarkdownEdit.make({
+			offset: target.insertAt,
+			length: 0,
+			content: `${key}: ${value}${newline}`
+		});
+		case "replaceScalar": {
+			const quoted = target.quote === "single-quoted" ? `'${value}'` : target.quote === "double-quoted" ? `"${value}"` : value;
+			return MarkdownEdit.make({
+				offset: target.start,
+				length: target.end - target.start,
+				content: quoted
+			});
+		}
+	}
+};
+/**
 * A whole `generated:` block mapping, appended as the LAST top-level key
 * (issue #73) — block style, matching how this repository writes every
 * `generated:` and how `splice`'s own `absent` case writes `verified:`.
@@ -106,4 +130,4 @@ const spliceGeneratedBlock = (target, fields, newline) => MarkdownEdit.make({
 });
 
 //#endregion
-export { splice, spliceGenerated, spliceGeneratedBlock, spliceGeneratedFields };
+export { splice, spliceGenerated, spliceGeneratedBlock, spliceGeneratedFields, spliceTopLevelScalar };

package/version.js

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