@okfit/profiles 0.2.0 → 0.3.1

package/Derivation.js

@@ -1,6 +1,6 @@
 import { GitHistory } from "./GitHistory.js";
 import { Actor, OkfitConfig } from "@okfit/core";
-import { DateTime, Duration, Effect, FileSystem, Option, Path, Schema } from "effect";
+import { Crypto, DateTime, Duration, Effect, Encoding, FileSystem, Option, Path, Schema } from "effect";
 import { Git } from "@effected/git";
 import { FrontmatterSource } from "@effected/markdown";
 
@@ -39,6 +39,10 @@ const FALLBACK_STALE_AFTER = Duration.days(90);
 const decodeActor = Schema.decodeSync(Actor);
 const normalise = (text) => text.replace(/\r\n?/g, "\n").trimEnd();
 const body = (text) => normalise(FrontmatterSource.split(text).body);
+const bodyDigest = (text) => Effect.gen(function* () {
+	const bytes = yield* (yield* Crypto.Crypto).digest("SHA-256", new TextEncoder().encode(body(text)));
+	return Encoding.encodeHex(bytes);
+});
 /** The text before the first `@` (the whole value when there is none), or undefined when empty or containing whitespace. */
 const localPartOf = (email) => {
 	if (email === void 0) return void 0;
@@ -94,6 +98,12 @@ var Derivation = class {
 	*/
 	static body = body;
 	/**
+	* Lowercase 64-char hex sha256 of `Derivation.body(text)`, through `effect`'s platform-agnostic
+	* `Crypto` service (issue #19). Same normalization as `body`, so a frontmatter-only edit or a
+	* `core.autocrlf` worktree never changes the digest.
+	*/
+	static bodyDigest = bodyDigest;
+	/**
 	* Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
 	*  1. `root = Git.repoRoot(dirname(file))`: a file outside any repository surfaces `NotARepositoryError`;
 	*     submodules and worktrees work because the question is asked from the file's directory (P-39).

package/Provenance.js

@@ -12,13 +12,23 @@ const encodeAt = Schema.encodeSync(Timestamp);
 * like every other lint (S-7). `Profile.check` and `ProfileDiagnosticCode`
 * are unchanged.
 *
-* Runs `Derivation.generatedAt` per concept, skips uncommitted bodies and
-* concepts without a `generated` block, and returns `[]` the moment a
-* `NotARepositoryError` surfaces: a bundle outside git has nothing to
-* derive for any concept, so the first occurrence short-circuits the whole
-* walk, not just the concept that triggered it (S-8). Emits no `range`
-* (S-12, Judge note 7): `Diagnostic.range` is `Schema.optionalKey` and is
-* simply omitted.
+* Two tiers per concept (issue #19, body-digest design): when
+* `generated.body_sha256` is present, drift is decided ENTIRELY by comparing it to
+* `Derivation.bodyDigest` of the concept's current source -- no git call at
+* all, so this works for a dirty worktree too (that is the point: an edited
+* body is caught immediately, before it is even committed) and survives a
+* squash/rebase merge that only rewrites commit dates, since the body
+* itself, and therefore its digest, never changed. When `body_sha256` is
+* absent (an un-migrated concept), this falls back to the original
+* git-derived date comparison against `Derivation.generatedAt`, preserving
+* `--skip-provenance`'s meaning for bundles that have not run `okfit sync`
+* since this field was introduced.
+*
+* The tier-2 fallback returns `[]` the moment a `NotARepositoryError`
+* surfaces: a bundle outside git has nothing to derive for any concept still
+* on tier 2, so the first occurrence short-circuits the whole walk, not just
+* the concept that triggered it (S-8). Emits no `range` (S-12, Judge note
+* 7): `Diagnostic.range` is `Schema.optionalKey` and is simply omitted.
 *
 * `Provenance.lint` is total over severity (S-28, amending Judge note 3):
 * when `OkfitConfig.severityFor(config, "generated-at-drift")` resolves to
@@ -27,17 +37,42 @@ const encodeAt = Schema.encodeSync(Timestamp);
 * `"off"` away. `validate/run.ts` (the CLI) still gates on `"off"` before
 * calling at all; the two agree by construction (both skip the walk).
 *
+* A third, optional options argument carries `skipGitTier`: when `true`, a
+* concept that falls through to tier 2 (no `generated.body_sha256`
+* recorded) is skipped entirely -- no `Derivation.generatedAt` call, no
+* git spawn at all -- while tier 1 still runs, unaffected, for every
+* concept that DOES carry a digest. This is a runtime skip, not a
+* type-level narrowing: the R channel still lists `Git | GitHistory` even
+* when every call happens to skip them, since the type describes what the
+* function CAN require, not what one particular call ends up using.
+* Defaults to `false`, so every existing caller keeps its current
+* behavior unchanged.
+*
 * @public
 */
 var Provenance = class {
 	constructor() {}
-	static lint = Effect.fn("Provenance.lint")(function* (bundle, config) {
+	static lint = Effect.fn("Provenance.lint")(function* (bundle, config, options) {
 		const severity = OkfitConfig.severityFor(config, "generated-at-drift");
 		if (severity === "off") return [];
+		const skipGitTier = options?.skipGitTier === true;
 		const path = yield* Path.Path;
 		const diagnostics = [];
 		for (const [, concept] of bundle.concepts) {
 			if (concept.frontmatter.generated === void 0) continue;
+			const recordedDigest = concept.frontmatter.generated.body_sha256;
+			if (recordedDigest !== void 0) {
+				const currentDigest = yield* Derivation.bodyDigest(concept.document.source);
+				if (currentDigest === recordedDigest) continue;
+				diagnostics.push(Diagnostic.make({
+					file: concept.path,
+					code: "generated-at-drift",
+					severity,
+					message: `the body has changed since generated.at was last stamped: generated.body_sha256 is ${recordedDigest}, the current body hashes to ${currentDigest}`
+				}));
+				continue;
+			}
+			if (skipGitTier) continue;
 			const file = path.join(bundle.root, concept.path);
 			const derived = yield* Derivation.generatedAt({ file }).pipe(Effect.catchTag("NotARepositoryError", () => Effect.succeed(void 0)));
 			if (derived === void 0) return [];

package/README.md

@@ -116,6 +116,7 @@ Each directory carries its own `index.md`. What `okfit init` writes into these f
 - **`generated.at` is the author date, not the stamp date (P-4).** Walking a path's git history newest-first, the commit that changed the body is the one whose blob first differs from its predecessor's; that commit's *author* date (`%aI`) is `generated.at`. Its committer date, author name, and author email are carried on the result for callers that want a history-based policy later, but `generated.at` itself is never the date of a later frontmatter-only stamp.
 - **The path log is `@effected/git`'s `Git.log(cwd, { paths: [path], follow: true, firstParentDiffMerges: true })` (P-5, amended P-46, decision 56).** `firstParentDiffMerges` surfaces a conflict-resolving merge whose blob differs from both parents (probed on git 2.54.0), which plain `--follow` can omit and which would otherwise attribute that body change to the wrong commit. `Git.log`'s unconditional `-z` makes `--name-only` emit paths raw — no C-style quoting — so no `core.quotePath` override is needed and a path containing a space, a quote, or a newline round-trips verbatim. The dirty check compares the worktree body against `Git.show(root, "HEAD", path)`, never against the newest log entry. `--follow`'s rename detection can itself stop at a commit that renames a file and rewrites its content enough that git no longer treats it as a continuation of the same history; when that happens, `generated.at` answers that rename commit rather than an older one.
 - **Uncommitted is the caller's to interpret (P-10).** `Derivation.generatedAt` reports `{ _tag: "uncommitted", reason: "untracked" | "dirty" | "unborn" }` and never substitutes `now`. The recommended policy, followed by the snippet below: omit `generated.at` entirely until the body is committed.
+- **The body digest answers "has the body changed", where dates cannot (issue #19).** `Derivation.bodyDigest(text)` is a sha256, hex-encoded, over the same normalised body `Derivation.body` produces (CRLF and lone CR to LF, trailing whitespace at end of text removed), so a `core.autocrlf` worktree and a trailing-newline change hash identically and a frontmatter-only edit does not move the digest at all. It is computed through effect's own `Crypto` service rather than `node:crypto`, so it carries `Crypto.Crypto` in its R channel; `NodeServices.layer` already supplies it wherever this package is used. `okfit sync` records it as `generated.body_sha256` — okfit's own extension key, not an OKF v0.2 field — and `Provenance.lint` compares it. Git cannot make this judgement on its own: the stamp lives in the same blob as the body, so a squash merge (one new commit carrying both) is indistinguishable by history from a body edited without a re-stamp.
 - **Human actor resolution (P-13).** Given git identity `{ name?, email? }` and `config.actors.humans`, the first hit wins: (1) a `human:<id>` entry whose id matches the email's local part or the name's slug, case-insensitively (config spelling returned); (2) `human:<local part>`; (3) `human:<slug of name>`; (4) unresolved. The slug lowercases `name`, replaces runs of whitespace and characters outside `[A-Za-z0-9._-]` with `-`, and trims leading and trailing `-`.
 - **Identity is read at merged config scope (P-15).** `Derivation.generatedBy` calls `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` with no `scope` option. Environment overrides (`GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `EMAIL`, `user.useConfigOnly`) are out of scope for phase 1.
 - **`stale_after` is pure addition (P-19).** `Derivation.staleAfter(from, config)` is `from + (config.lifecycle?.default_stale_after ?? OkfitConfig.DEFAULTS.lifecycle.default_stale_after)`, falling back to 90 days. `from` should be `generated.at` when the provenance is `committed`, otherwise the caller's own `now`; re-stamp whenever `generated.at` changes.
@@ -134,19 +135,33 @@ Frontmatter serialisation, the uncommitted policy's enforcement, `now`, layer co
 
 ## Provenance
 
-`Provenance.lint(bundle, config)` is the `generated-at-drift` lint
-(`lint.generated_at_drift`, config default `"info"`): it walks
-`Derivation.generatedAt` once per concept with a `generated` block, and
-reports a core `Diagnostic` when a committed body's `generated.at` is
-missing or does not match the derived instant (compared as decoded
-`DateTime.Utc` values, never encoded strings). It is silent for an
-uncommitted body, for a concept with no `generated` block, and returns `[]`
-the moment it discovers the bundle is outside a git repository at all. It
-emits no `range` — the message carries both instants and a 7-character
-sha, which is what a reader acts on. It is a plain facade over
-`Derivation`, not a `Profile` member: `severityFor`, the `[lint]` table,
-the renderers, the PostToolUse hook, and the MCP `validate_bundle` tool all
-treat its `Diagnostic`s like every other lint. It is total over severity
+`Provenance.lint(bundle, config, options?)` is the `generated-at-drift`
+lint (`lint.generated_at_drift`, config default `"warn"`), and it runs in
+two tiers (issue #19).
+
+Tier 1 applies to a concept that records `generated.body_sha256`: the
+recorded digest is compared against
+`Derivation.bodyDigest(concept.document.source)`, a pure comparison over
+text already in memory with no git call and no filesystem read. Drift here
+means the body has changed since it was last stamped -- never that a squash
+or rebase merge minted a new author date for the commit that carried it.
+Because the comparison is against the worktree, a body edited but not yet
+committed reports immediately.
+
+Tier 2 applies to a concept stamped before the digest field existed: the
+original walk, one `Derivation.generatedAt` per concept, reporting when a
+committed body's `generated.at` is missing or is not the derived instant
+(compared as decoded `DateTime.Utc` values, never encoded strings). Tier 2
+is silent for an uncommitted body and returns `[]` the moment it discovers
+the bundle is outside a git repository at all.
+
+A concept with no `generated` block is skipped by both tiers. The lint
+emits no `range` -- tier 1's message carries both digests and tier 2's
+carries both instants and a 7-character sha, which is what a reader acts
+on. It is a plain facade over `Derivation`, not a `Profile` member:
+`severityFor`, the `[lint]` table, the renderers, the PostToolUse hook, and
+the MCP `validate_bundle` tool all treat its `Diagnostic`s like every other
+lint. It is total over severity
 (S-28): when the resolved `generated-at-drift` severity is `"off"` it
 returns `[]` before any per-concept work and before any git call, so it is
 safe to call at any severity. The CLI (`okfit validate`, `okfit sync`'s own

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
+import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
 import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
 import { Actor, Diagnostic, DiagnosticRange, LoadedBundle, OkfitConfig } from "@okfit/core";
 import { ChildProcessSpawner } from "effect/unstable/process";
@@ -239,6 +239,12 @@ export declare class Derivation {
    * text removed (P-6). Pure. Applied to both sides of every comparison so `core.autocrlf` worktrees compare clean.
    */
   static readonly body: (text: string) => string;
+  /**
+   * Lowercase 64-char hex sha256 of `Derivation.body(text)`, through `effect`'s platform-agnostic
+   * `Crypto` service (issue #19). Same normalization as `body`, so a frontmatter-only edit or a
+   * `core.autocrlf` worktree never changes the digest.
+   */
+  static readonly bodyDigest: (text: string) => Effect.Effect<string, PlatformError.PlatformError, Crypto.Crypto>;
   /**
    * Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
    *  1. `root = Git.repoRoot(dirname(file))`: a file outside any repository surfaces `NotARepositoryError`;
@@ -389,13 +395,23 @@ export declare class Profiles {
  * like every other lint (S-7). `Profile.check` and `ProfileDiagnosticCode`
  * are unchanged.
  *
- * Runs `Derivation.generatedAt` per concept, skips uncommitted bodies and
- * concepts without a `generated` block, and returns `[]` the moment a
- * `NotARepositoryError` surfaces: a bundle outside git has nothing to
- * derive for any concept, so the first occurrence short-circuits the whole
- * walk, not just the concept that triggered it (S-8). Emits no `range`
- * (S-12, Judge note 7): `Diagnostic.range` is `Schema.optionalKey` and is
- * simply omitted.
+ * Two tiers per concept (issue #19, body-digest design): when
+ * `generated.body_sha256` is present, drift is decided ENTIRELY by comparing it to
+ * `Derivation.bodyDigest` of the concept's current source -- no git call at
+ * all, so this works for a dirty worktree too (that is the point: an edited
+ * body is caught immediately, before it is even committed) and survives a
+ * squash/rebase merge that only rewrites commit dates, since the body
+ * itself, and therefore its digest, never changed. When `body_sha256` is
+ * absent (an un-migrated concept), this falls back to the original
+ * git-derived date comparison against `Derivation.generatedAt`, preserving
+ * `--skip-provenance`'s meaning for bundles that have not run `okfit sync`
+ * since this field was introduced.
+ *
+ * The tier-2 fallback returns `[]` the moment a `NotARepositoryError`
+ * surfaces: a bundle outside git has nothing to derive for any concept still
+ * on tier 2, so the first occurrence short-circuits the whole walk, not just
+ * the concept that triggered it (S-8). Emits no `range` (S-12, Judge note
+ * 7): `Diagnostic.range` is `Schema.optionalKey` and is simply omitted.
  *
  * `Provenance.lint` is total over severity (S-28, amending Judge note 3):
  * when `OkfitConfig.severityFor(config, "generated-at-drift")` resolves to
@@ -404,11 +420,24 @@ export declare class Profiles {
  * `"off"` away. `validate/run.ts` (the CLI) still gates on `"off"` before
  * calling at all; the two agree by construction (both skip the walk).
  *
+ * A third, optional options argument carries `skipGitTier`: when `true`, a
+ * concept that falls through to tier 2 (no `generated.body_sha256`
+ * recorded) is skipped entirely -- no `Derivation.generatedAt` call, no
+ * git spawn at all -- while tier 1 still runs, unaffected, for every
+ * concept that DOES carry a digest. This is a runtime skip, not a
+ * type-level narrowing: the R channel still lists `Git | GitHistory` even
+ * when every call happens to skip them, since the type describes what the
+ * function CAN require, not what one particular call ends up using.
+ * Defaults to `false`, so every existing caller keeps its current
+ * behavior unchanged.
+ *
  * @public
  */
 export declare class Provenance {
   private constructor();
-  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path>;
+  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, options?: {
+    readonly skipGitTier?: boolean;
+  }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Crypto.Crypto>;
 }
 //#endregion
 export type { GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, UncommittedReason, Writer };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/profiles",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"private": false,
 	"description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
 	"keywords": [
@@ -35,10 +35,10 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/git": "^0.12.0",
-		"@effected/markdown": "^0.9.0",
-		"@okfit/core": "^0.2.0",
-		"effect": "4.0.0-rc.112"
+		"@effected/git": "^0.15.0",
+		"@effected/markdown": "^0.10.0",
+		"@okfit/core": "^0.3.1",
+		"effect": "4.0.0-rc.115"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/tsdoc-metadata.json

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