@okfit/engine 0.1.0 → 0.2.1

package/config/anchor.js

@@ -15,7 +15,7 @@ const anchorForExplicit = (configPath, path) => {
 /**
 * K-12's project root, as amended by K-58 and C1-2, in order:
 *
-* 1. `pathArg`, if given. `Argument.path` has already resolved it absolute.
+* 1. `pathArg`, if given. `Argument.Path` has already resolved it absolute.
 * 2. otherwise, if `--config` was given: `anchorForExplicit` applied to that
 *    path.
 * 3. otherwise, if a config was discovered by the `"project"` resolver

package/index.d.ts

@@ -1,5 +1,5 @@
 import { BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, LoadedBundle, OkfitConfig, OkfitConfigFile, ValidationReport } from "@okfit/core";
-import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Runtime, Schema } from "effect";
+import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, 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";
@@ -32,7 +32,7 @@ interface DiscoveredConfig {
 /**
  * K-12's project root, as amended by K-58 and C1-2, in order:
  *
- * 1. `pathArg`, if given. `Argument.path` has already resolved it absolute.
+ * 1. `pathArg`, if given. `Argument.Path` has already resolved it absolute.
  * 2. otherwise, if `--config` was given: `anchorForExplicit` applied to that
  *    path.
  * 3. otherwise, if a config was discovered by the `"project"` resolver
@@ -714,7 +714,7 @@ interface SyncResult {
  *
  * @public
  */
-export declare const runSync: (options: SyncOptions) => Effect.Effect<SyncResult, BundleLoadError | GeneratedAtError, Git | GitHistory | FileSystem.FileSystem | Path.Path>;
+export declare const runSync: (options: SyncOptions) => Effect.Effect<SyncResult, BundleLoadError | GeneratedAtError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Crypto.Crypto>;
 //#endregion
 //#region src/render/sync.d.ts
 /** @public */
@@ -860,13 +860,17 @@ interface RunOptions {
   /** `OKFIT_NOW` or `DateTime.now`, from `bin.ts` (K-47); enables the `stale` rule (D-34). */
   readonly now: DateTime.Utc;
   /**
-   * S-31: skip `Provenance.lint`'s git tier for this one invocation,
-   * without touching the project's `[lint]` table. `commands/validate.ts`
-   * threads `--skip-provenance` here; the PostToolUse hook passes the flag
-   * so an edit-time `validate` stays git-free even when the config leaves
-   * `generated-at-drift` at its default severity. Defaults to `false`, and
-   * is checked the same way `severity === "off"` already is — `run` skips
-   * the walk when EITHER is true.
+   * S-31: skip `Provenance.lint`'s git TIER (tier 2, the git-derived date
+   * comparison for concepts with no recorded `generated.body_sha256`)
+   * for this one invocation, without touching the project's `[lint]`
+   * table. `commands/validate.ts` threads `--skip-provenance` here; the
+   * PostToolUse hook passes the flag so an edit-time `validate` stays
+   * git-free even when the config leaves `generated-at-drift` at its
+   * default severity. Tier 1 (the pure, in-memory body-digest comparison)
+   * still runs regardless — that is exactly the signal edit time wants,
+   * at the cost of one sha256 over text already in memory. Defaults to
+   * `false`; `run` still gates the whole lint call on `severity ===
+   * "off"`, but no longer on this flag.
    */
   readonly skipProvenance?: boolean;
 }
@@ -879,11 +883,15 @@ interface RunResult {
 }
 /**
  * Load, validate both tiers, run the profile check, then — UNLESS the
- * `generated-at-drift` lint is `off` OR `options.skipProvenance` is `true`
- * — run `Provenance.lint` and append its `Diagnostic`s to `report.lint`.
- * The "skip the git walk entirely" gate lives HERE, in `run`, not inside
- * `Provenance.lint` (S-8's own wording): a bundle configured `off`, or a
- * caller that passed `--skip-provenance`, never pays for a git spawn
+ * `generated-at-drift` lint is `off` — run `Provenance.lint` and append its
+ * `Diagnostic`s to `report.lint`. The "skip the whole lint" gate lives
+ * HERE, in `run`: a bundle configured `off` never calls `Provenance.lint`
+ * at all. `options.skipProvenance` is no longer that gate — it is threaded
+ * through as `Provenance.lint`'s `skipGitTier` option instead, so tier 1
+ * (the pure, in-memory `generated.body_sha256` comparison) still runs and
+ * still reports drift even when `skipProvenance` is `true`; only tier 2
+ * (the git-derived date comparison, for concepts with no recorded digest)
+ * is skipped, and with it the only git spawn `Provenance.lint` can make
  * (S-31). An `error` severity on the appended diagnostics yields exit `1`
  * through the EXISTING lint-tier rule in `render/exit.ts` — no renderer
  * branch, no new `DiagnosticSource`, since these diagnostics flow through
@@ -899,7 +907,7 @@ interface RunResult {
  *
  * @public
  */
-export declare const run: (options: RunOptions) => Effect.Effect<RunResult, BundleLoadError | GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Git | GitHistory>;
+export declare const run: (options: RunOptions) => Effect.Effect<RunResult, BundleLoadError | GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Git | GitHistory | Crypto.Crypto>;
 //#endregion
 //#region src/verify/run.d.ts
 /** @internal */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/engine",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"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,21 +34,21 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effect/platform-node": "4.0.0-rc.112",
-		"@effected/app": "^0.15.0",
-		"@effected/config-file": "^0.7.0",
-		"@effected/git": "^0.12.0",
-		"@effected/glob": "^0.5.0",
-		"@effected/jsonc": "^0.9.0",
-		"@effected/markdown": "^0.9.1",
-		"@effected/store": "^0.7.0",
-		"@effected/toml": "^0.6.0",
-		"@effected/walker": "^0.7.0",
-		"@effected/xdg": "^0.4.1",
-		"@effected/yaml": "^0.14.0",
-		"@okfit/core": "0.2.0",
-		"@okfit/profiles": "0.2.0",
-		"effect": "4.0.0-rc.112"
+		"@effect/platform-node": "4.0.0-rc.115",
+		"@effected/app": "^0.16.0",
+		"@effected/config-file": "^0.8.0",
+		"@effected/git": "^0.15.0",
+		"@effected/glob": "^0.6.0",
+		"@effected/jsonc": "^0.11.0",
+		"@effected/markdown": "^0.10.0",
+		"@effected/store": "^0.8.0",
+		"@effected/toml": "^0.7.0",
+		"@effected/walker": "^0.8.0",
+		"@effected/xdg": "^0.5.0",
+		"@effected/yaml": "^0.15.0",
+		"@okfit/core": "0.3.1",
+		"@okfit/profiles": "0.3.1",
+		"effect": "4.0.0-rc.115"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/sync/generated.js

@@ -1,8 +1,9 @@
-import { detectNewline, locateGenerated, stripBom } from "../verify/locate.js";
-import { spliceGenerated } from "../verify/splice.js";
+import { detectNewline, locateGenerated, locateGeneratedBodySha256, stripBom } from "../verify/locate.js";
+import { spliceGeneratedFields } from "../verify/splice.js";
 import { writeAtomic } from "./write.js";
 import { Timestamp } from "@okfit/core";
-import { DateTime, Effect, FileSystem, Path, Schema } from "effect";
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { Derivation } from "@okfit/profiles";
 import { MarkdownEdit } from "@effected/markdown";
 
 //#region src/sync/generated.ts
@@ -73,8 +74,8 @@ const syncGenerated = Effect.fn("okfit/sync/syncGenerated")(function* (bundle, p
 			});
 			continue;
 		}
-		const recorded = generated.at;
-		if (recorded !== void 0 && DateTime.Equivalence(recorded, derived.at)) {
+		const currentDigest = yield* Derivation.bodyDigest(concept.document.source);
+		if (generated.body_sha256 !== void 0 && generated.body_sha256 === currentDigest) {
 			unchanged.push(id);
 			continue;
 		}
@@ -82,8 +83,9 @@ const syncGenerated = Effect.fn("okfit/sync/syncGenerated")(function* (bundle, p
 		const source = yield* fs.readFileString(absolutePath);
 		const { text, bom } = stripBom(source);
 		const newline = detectNewline(text);
-		const located = yield* locateGenerated(text).pipe(Effect.orDie);
-		if (located._tag === "unsupported") {
+		const atLocated = yield* locateGenerated(text).pipe(Effect.orDie);
+		const bodySha256Located = yield* locateGeneratedBodySha256(text).pipe(Effect.orDie);
+		if (atLocated._tag === "unsupported" || bodySha256Located._tag === "unsupported") {
 			skipped.push({
 				id,
 				reason: "generated-unsupported"
@@ -91,8 +93,8 @@ const syncGenerated = Effect.fn("okfit/sync/syncGenerated")(function* (bundle, p
 			continue;
 		}
 		const encodedAt = encodeAt(derived.at);
-		const edit = spliceGenerated(located, encodedAt, newline);
-		const finalText = bom + MarkdownEdit.applyAll(text, [edit]);
+		const edits = spliceGeneratedFields(atLocated, bodySha256Located, encodedAt, currentDigest, newline);
+		const finalText = bom + MarkdownEdit.applyAll(text, edits);
 		if (dryRun) {
 			written.push(id);
 			continue;

package/tsdoc-metadata.json

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

package/validate/run.js

@@ -21,11 +21,15 @@ import { Provenance } from "@okfit/profiles";
 var Now = class extends Context.Service()("@okfit/engine/Now") {};
 /**
 * Load, validate both tiers, run the profile check, then — UNLESS the
-* `generated-at-drift` lint is `off` OR `options.skipProvenance` is `true`
-* — run `Provenance.lint` and append its `Diagnostic`s to `report.lint`.
-* The "skip the git walk entirely" gate lives HERE, in `run`, not inside
-* `Provenance.lint` (S-8's own wording): a bundle configured `off`, or a
-* caller that passed `--skip-provenance`, never pays for a git spawn
+* `generated-at-drift` lint is `off` — run `Provenance.lint` and append its
+* `Diagnostic`s to `report.lint`. The "skip the whole lint" gate lives
+* HERE, in `run`: a bundle configured `off` never calls `Provenance.lint`
+* at all. `options.skipProvenance` is no longer that gate — it is threaded
+* through as `Provenance.lint`'s `skipGitTier` option instead, so tier 1
+* (the pure, in-memory `generated.body_sha256` comparison) still runs and
+* still reports drift even when `skipProvenance` is `true`; only tier 2
+* (the git-derived date comparison, for concepts with no recorded digest)
+* is skipped, and with it the only git spawn `Provenance.lint` can make
 * (S-31). An `error` severity on the appended diagnostics yields exit `1`
 * through the EXISTING lint-tier rule in `render/exit.ts` — no renderer
 * branch, no new `DiagnosticSource`, since these diagnostics flow through
@@ -48,7 +52,7 @@ const run = (options) => Effect.gen(function* () {
 		onNone: () => [],
 		onSome: (profile) => profile.check(bundle)
 	});
-	const provenance = OkfitConfig.severityFor(options.config, "generated-at-drift") === "off" || options.skipProvenance === true ? [] : yield* Provenance.lint(bundle, options.config);
+	const provenance = OkfitConfig.severityFor(options.config, "generated-at-drift") === "off" ? [] : yield* Provenance.lint(bundle, options.config, { skipGitTier: options.skipProvenance === true });
 	return {
 		bundle,
 		report: {

package/verify/locate.js

@@ -157,7 +157,7 @@ const locate = Effect.fn("okfit/verify/locate")(function* (source) {
 *
 * @internal
 */
-const locateGenerated = Effect.fn("okfit/verify/locateGenerated")(function* (source) {
+const locateGeneratedField = Effect.fn("okfit/verify/locateGeneratedField")(function* (source, field) {
 	const block = FrontmatterSource.split(source).frontmatter;
 	if (block === void 0) return {
 		_tag: "unsupported",
@@ -205,8 +205,8 @@ const locateGenerated = Effect.fn("okfit/verify/locateGenerated")(function* (sou
 		shape: "flow-mapping"
 	};
 	const indent = indentAt(value, node.offset);
-	const atPair = node.items.find((item) => item.key instanceof YamlScalar && item.key.value === "at");
-	if (atPair === void 0) {
+	const fieldPair = node.items.find((item) => item.key instanceof YamlScalar && item.key.value === field);
+	if (fieldPair === void 0) {
 		const last = node.items[node.items.length - 1];
 		if (last === void 0) return {
 			_tag: "unsupported",
@@ -220,30 +220,40 @@ const locateGenerated = Effect.fn("okfit/verify/locateGenerated")(function* (sou
 			indent
 		};
 	}
-	const atValue = atPair.value;
-	if (atValue === null) return {
+	const fieldValue = fieldPair.value;
+	if (fieldValue === null) return {
 		_tag: "unsupported",
-		shape: "at-empty"
+		shape: `${field}-empty`
 	};
-	if (atValue instanceof YamlAlias) return {
+	if (fieldValue instanceof YamlAlias) return {
 		_tag: "unsupported",
 		shape: "alias"
 	};
-	if (!(atValue instanceof YamlScalar)) return {
+	if (!(fieldValue instanceof YamlScalar)) return {
 		_tag: "unsupported",
-		shape: "at-not-scalar"
+		shape: `${field}-not-scalar`
 	};
-	if (atValue.style === "block-literal" || atValue.style === "block-folded") return {
+	if (fieldValue.style === "block-literal" || fieldValue.style === "block-folded") return {
 		_tag: "unsupported",
-		shape: "at-block-scalar"
+		shape: `${field}-block-scalar`
 	};
 	return {
 		_tag: "replaceScalar",
-		start: valueStart + atValue.offset,
-		end: valueStart + atValue.offset + atValue.length,
-		quote: atValue.style
+		start: valueStart + fieldValue.offset,
+		end: valueStart + fieldValue.offset + fieldValue.length,
+		quote: fieldValue.style
 	};
 });
+const locateGenerated = (source) => locateGeneratedField(source, "at");
+/**
+* As {@link locateGenerated}, but for the top-level `generated.body_sha256`
+* key (issue #19). Shares every branch with `locateGenerated` -- the two
+* fields are siblings of the same `generated:` block mapping -- parametrized
+* only by which key name is sought.
+*
+* @internal
+*/
+const locateGeneratedBodySha256 = (source) => locateGeneratedField(source, "body_sha256");
 
 //#endregion
-export { detectNewline, documentNewline, indentAt, locate, locateGenerated, stripBom };
+export { detectNewline, documentNewline, indentAt, locate, locateGenerated, locateGeneratedBodySha256, stripBom };

package/verify/splice.js

@@ -45,23 +45,24 @@ const splice = (target, entry, newline) => {
 };
 /**
 * Build the one edit for `target` (contract §6.1). Never calls a YAML
-* stringifier: the only syntax emitted is the indent, `at: `, the
-* preserved quote character (if any), and `newline`. `encodedAt` is
-* already `Schema.encodeSync(Timestamp)`'d by the caller (S-1: splice,
-* never `YamlFormat.modify` — it drops quote style and re-normalises line
-* endings, V-12/V-15 violations `sync/generated.ts` cannot afford).
+* stringifier: the only syntax emitted is the indent, `<field>: `, the
+* preserved quote character (if any), and `newline`. `value` is already
+* encoded by the caller -- `Schema.encodeSync(Timestamp)`'d for `at`, the raw
+* lowercase hex digest for `body_sha256` (S-1: splice, never `YamlFormat.
+* modify` — it drops quote style and re-normalises line endings, V-12/V-15
+* violations `sync/generated.ts` cannot afford).
 *
 * @internal
 */
-const spliceGenerated = (target, encodedAt, newline) => {
+const spliceGenerated = (target, value, newline, field = "at") => {
 	switch (target._tag) {
 		case "insertAfterLastKey": return MarkdownEdit.make({
 			offset: target.insertAt,
 			length: 0,
-			content: `${target.indent}at: ${encodedAt}${newline}`
+			content: `${target.indent}${field}: ${value}${newline}`
 		});
 		case "replaceScalar": {
-			const quoted = target.quote === "single-quoted" ? `'${encodedAt}'` : target.quote === "double-quoted" ? `"${encodedAt}"` : encodedAt;
+			const quoted = target.quote === "single-quoted" ? `'${value}'` : target.quote === "double-quoted" ? `"${value}"` : value;
 			return MarkdownEdit.make({
 				offset: target.start,
 				length: target.end - target.start,
@@ -70,6 +71,27 @@ const spliceGenerated = (target, encodedAt, newline) => {
 		}
 	}
 };
+/**
+* Build the edit(s) that write BOTH `generated.at` and `generated.
+* body_sha256` together (issue #19: `sync/generated.ts` never writes one
+* without the other). Each field's own `spliceGenerated` edit is used when
+* the two land at different offsets; when both are absent they resolve to
+* the identical `insertAfterLastKey` anchor (the mapping's last existing
+* key), and inserting two zero-length edits at the same offset is exactly
+* the "overlapping edits" case `MarkdownEdit.applyAll` treats as a
+* programmer error -- so that one case is merged into a single edit whose
+* content carries both lines, `at` first.
+*
+* @internal
+*/
+const spliceGeneratedFields = (atTarget, bodySha256Target, encodedAt, bodySha256, newline) => {
+	if (atTarget._tag === "insertAfterLastKey" && bodySha256Target._tag === "insertAfterLastKey" && atTarget.insertAt === bodySha256Target.insertAt) return [MarkdownEdit.make({
+		offset: atTarget.insertAt,
+		length: 0,
+		content: `${atTarget.indent}at: ${encodedAt}${newline}${bodySha256Target.indent}body_sha256: ${bodySha256}${newline}`
+	})];
+	return [spliceGenerated(atTarget, encodedAt, newline, "at"), spliceGenerated(bodySha256Target, bodySha256, newline, "body_sha256")];
+};
 
 //#endregion
-export { splice, spliceGenerated };
+export { splice, spliceGenerated, spliceGeneratedFields };