@okfit/profiles 0.13.0 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/Canonical.js CHANGED
@@ -1,4 +1,6 @@
1
1
  import { body } from "./internal/body.js";
2
+ import { Result, Schema } from "effect";
3
+ import { JsoncCanonicalizeOptions, JsoncFingerprint } from "@effected/jsonc";
2
4
 
3
5
  // src/Canonical.ts
4
6
  /** Top-level keys that are bookkeeping, not authored content (spec section 4). */
@@ -10,26 +12,43 @@ const EXCLUDED_KEYS = /* @__PURE__ */ new Set([
10
12
  "status",
11
13
  "timestamp"
12
14
  ]);
13
- /** `JSON.stringify` omits these in an object and writes `null` for them in an array. */
14
- const isSkipped = (value) => value === void 0 || typeof value === "function" || typeof value === "symbol";
15
15
  /**
16
- * Canonical JSON: object keys sorted (`Array.prototype.toSorted`, UTF-16 code units)
17
- * at every depth; arrays keep their order. Byte-for-byte `JSON.stringify` of the
18
- * sorted value for every JSON-representable input, plus one extension: a `bigint`
19
- * (what the YAML decoder yields for an integer beyond 2^53, e.g. `ticket:
20
- * 123456789012345678901`) is written as its bare decimal literal. A literal cannot
21
- * collide with a string (strings are quoted) and is deterministic, where
22
- * `JSON.stringify` throws `TypeError` and would defect every caller that hashes.
16
+ * `@effected/jsonc`'s RFC 8785 canonicalization, relaxed only where okfit's frontmatter needs it: a `bigint`
17
+ * (what the YAML decoder yields for an integer beyond 2^53) is written as its bare decimal literal, an
18
+ * `undefined` member is omitted, a non-finite number is `null`, and a `toJSON` value is serialized through
19
+ * it. These match `JSON.stringify` of the sorted value byte for byte. An unpaired surrogate is NOT relaxed:
20
+ * it is not well-formed Unicode, can only arrive through a YAML `\uD800`-style escape, and fails as a
21
+ * {@link ContentUnhashableError} instead of being hashed (okfit#327).
23
22
  */
24
- const json = (value) => {
25
- if (typeof value === "bigint") return value.toString();
26
- if (Array.isArray(value)) return `[${value.map((item) => isSkipped(item) ? "null" : json(item)).join(",")}]`;
27
- if (value !== null && typeof value === "object") {
28
- const record = value;
29
- if (typeof record.toJSON === "function") return json(record.toJSON());
30
- return `{${Object.keys(record).toSorted().filter((key) => !isSkipped(record[key])).map((key) => `${JSON.stringify(key)}:${json(record[key])}`).join(",")}}`;
23
+ const CANONICALIZE = JsoncCanonicalizeOptions.make({
24
+ bigint: "number",
25
+ undefined: "omit",
26
+ nonFinite: "null",
27
+ toJSON: "all"
28
+ });
29
+ /**
30
+ * A concept's content cannot be canonicalized for its digest, so it has none: most often a frontmatter
31
+ * string holding an unpaired surrogate (`"\uD800"`). `path` is the offending value's frontmatter path
32
+ * (`[]` for the frontmatter itself), `detail` the canonicalizer's reason.
33
+ *
34
+ * @public
35
+ */
36
+ var ContentUnhashableError = class extends Schema.TaggedError()("ContentUnhashableError", {
37
+ path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
38
+ detail: Schema.String
39
+ }) {
40
+ get message() {
41
+ return `${this.path.length === 0 ? "the frontmatter" : this.path.join(".")} cannot be hashed: ${this.detail}`;
31
42
  }
32
- return JSON.stringify(value);
43
+ };
44
+ /** `/frontmatter/a/0/b` to `["a", 0, "b"]` (RFC 6901 unescaping); a body or root pointer to `[]`. */
45
+ const frontmatterPath = (pointer) => {
46
+ const [, head, ...rest] = pointer.split("/");
47
+ if (head !== "frontmatter") return [];
48
+ return rest.map((token) => {
49
+ const key = token.replaceAll("~1", "/").replaceAll("~0", "~");
50
+ return /^(0|[1-9][0-9]*)$/.test(key) ? Number(key) : key;
51
+ });
33
52
  };
34
53
  const stripRendersDigests = (renders) => Array.isArray(renders) ? renders.map((entry) => {
35
54
  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return entry;
@@ -37,17 +56,20 @@ const stripRendersDigests = (renders) => Array.isArray(renders) ? renders.map((e
37
56
  return rest;
38
57
  }) : renders;
39
58
  /**
40
- * The exact string a content digest hashes: canonical JSON of the authored frontmatter
59
+ * The exact string a content digest hashes, or why there is none: canonical JSON of the authored frontmatter
41
60
  * (`raw` minus `Canonical.EXCLUDED_KEYS` and every `renders[].body`) and the
42
61
  * normalised body. `raw` is the parsed mapping (YAML 1.2 Core Schema: timestamps are
43
62
  * strings), so quoting, flow vs block style, key order and CRLF never change it.
44
63
  */
45
64
  const contentInput = (raw, source) => {
46
65
  const frontmatter = Object.fromEntries(Object.entries(raw).filter(([key]) => !EXCLUDED_KEYS.has(key)).map(([key, value]) => [key, key === "renders" ? stripRendersDigests(value) : value]));
47
- return json({
66
+ return Result.mapError(JsoncFingerprint.canonicalizeResult({
48
67
  body: body(source),
49
68
  frontmatter
50
- });
69
+ }, CANONICALIZE), (error) => new ContentUnhashableError({
70
+ path: frontmatterPath(error.path),
71
+ detail: error.detail
72
+ }));
51
73
  };
52
74
  /**
53
75
  * Canonical encoding for okfit's content digest.
@@ -58,10 +80,8 @@ var Canonical = class {
58
80
  constructor() {}
59
81
  /** Top-level frontmatter keys excluded from the content digest. */
60
82
  static EXCLUDED_KEYS = EXCLUDED_KEYS;
61
- /** Canonical JSON: sorted keys at every depth, array order kept; a `bigint` is its bare decimal literal. */
62
- static json = json;
63
- /** The exact string a content digest hashes. */
83
+ /** The exact string a content digest hashes, or a {@link ContentUnhashableError}. */
64
84
  static contentInput = contentInput;
65
85
  };
66
86
 
67
- export { Canonical };
87
+ export { Canonical, ContentUnhashableError };
package/Derivation.js CHANGED
@@ -1,10 +1,10 @@
1
- import { body } from "./internal/body.js";
2
1
  import { Canonical } from "./Canonical.js";
3
2
  import { GitHistory } from "./GitHistory.js";
3
+ import { body } from "./internal/body.js";
4
4
  import { Actor, OkfitConfig } from "@okfit/core";
5
5
  import { DateTime, Duration, Effect, FileSystem, Option, Path, Schema } from "effect";
6
- import { Git } from "@effected/git";
7
6
  import { JsoncFingerprint } from "@effected/jsonc";
7
+ import { Git } from "@effected/git";
8
8
 
9
9
  // src/Derivation.ts
10
10
  /**
@@ -65,7 +65,7 @@ const decodeActor = Schema.decodeSync(Actor);
65
65
  const digestFull = (text) => JsoncFingerprint.hashText(text);
66
66
  const digest = (text) => Effect.map(digestFull(text), (hex) => hex.slice(0, 16));
67
67
  const bodyDigest = (source) => digest(body(source));
68
- const contentDigest = (raw, source) => digest(Canonical.contentInput(raw, source));
68
+ const contentDigest = (raw, source) => Effect.flatMap(Effect.fromResult(Canonical.contentInput(raw, source)), digest);
69
69
  /** The text before the first `@` (the whole value when there is none), or undefined when empty or containing whitespace. */
70
70
  const localPartOf = (email) => {
71
71
  if (email === void 0) return void 0;
@@ -141,7 +141,7 @@ var Derivation = class Derivation {
141
141
  static digestFull = digestFull;
142
142
  /**
143
143
  * The okfit digest of a string: the first 16 lowercase hex characters of its SHA-256, through
144
- * `effect`'s platform-agnostic `Crypto` service.
144
+ * core's platform-agnostic `Digest` service.
145
145
  */
146
146
  static digest = digest;
147
147
  /**
@@ -157,7 +157,8 @@ var Derivation = class Derivation {
157
157
  static recordedBody = (concept) => concept.frontmatter.integrity?.generated?.body ?? concept.frontmatter.generated?.body_sha256?.slice(0, 16);
158
158
  /**
159
159
  * 16-hex digest of the canonical content input (`Canonical.contentInput`): authored frontmatter
160
- * plus the normalised body, insensitive to style, key order and CRLF.
160
+ * plus the normalised body, insensitive to style, key order and CRLF. Fails with
161
+ * {@link ContentUnhashableError} when the content cannot be canonicalized (an unpaired surrogate).
161
162
  */
162
163
  static contentDigest = contentDigest;
163
164
  /**
package/README.md CHANGED
@@ -290,7 +290,7 @@ Each directory carries its own `index.md`. What `okfit init` writes into these f
290
290
  - **`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.
291
291
  - **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.
292
292
  - **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.
293
- - **The body digest answers "has the body changed", where dates cannot (issue #19).** `Derivation.bodyDigest(text)` is a 16-hex SHA-256 prefix 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 `integrity.generated.body` — 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.
293
+ - **The body digest answers "has the body changed", where dates cannot (issue #19).** `Derivation.bodyDigest(text)` is a 16-hex SHA-256 prefix 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 core's `Digest` service (`effect/crypto`) rather than `node:crypto`, so it carries `Digest.Digest` in its R channel and cannot fail with a typed error; provide a `Digest` layer such as `NodeCrypto.layerDigest` from `@effect/platform-node` (`NodeServices.layer` carries no crypto since Effect 4.1). `okfit sync` records it as `integrity.generated.body` — 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.
294
294
  - **Human actor resolution (P-13).** Given git identity `{ name?, email? }` and `config.actors.humans`, the first hit wins: (1) `git config okfit.actor`, which must be a `human:<id>` with no `@` and no `*` or `?` (`ActorConfigInvalidError` otherwise); (2) a literal `human:<id>` entry (glob entries are skipped) whose id matches the email's local part or the name's slug, case-insensitively (config spelling returned); (3) `human:<local part>`; (4) `human:<slug of name>`; (5) unresolved (`HumanActorUnresolvedError`). `Derivation.verifier` runs that resolution and then checks the `[actors].humans` allow-list with core's `Actor.allowed`: an empty or absent list allows anyone, a non-empty one fails with `HumanActorNotAllowedError`, which is what `okfit verify`, `--revoke` and the language server's verify actions surface. okfit never stores an email; the trust signal reports `actor-not-allowed` (a `DriftReason`) for a verifier outside the list. The slug lowercases `name`, replaces runs of whitespace and characters outside `[A-Za-z0-9._-]` with `-`, and trims leading and trailing `-`.
295
295
  - **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.
296
296
  - **`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.
package/Trust.js CHANGED
@@ -1,13 +1,15 @@
1
1
  import { Derivation } from "./Derivation.js";
2
2
  import { Actor, Derive, Diagnostic, DiagnosticRange, OkfitConfig, Timestamp } from "@okfit/core";
3
- import { DateTime, Effect, Schema } from "effect";
3
+ import { DateTime, Effect, Result, Schema } from "effect";
4
4
 
5
5
  // src/Trust.ts
6
6
  const encodeAt = Schema.encodeSync(Timestamp);
7
7
  /**
8
8
  * Why a human verification no longer binds: the content changed, the entry has
9
- * no `integrity.verified` binding, a later human entry is not the bound one, or
10
- * the bound actor fails a non-empty `[actors].humans` allow-list.
9
+ * no `integrity.verified` binding, a later human entry is not the bound one, the
10
+ * bound actor fails a non-empty `[actors].humans` allow-list, or the content
11
+ * cannot be hashed at all (an unpaired surrogate; okfit#327), so the binding
12
+ * cannot be checked.
11
13
  *
12
14
  * @public
13
15
  */
@@ -15,7 +17,8 @@ const DriftReason = Schema.Literals([
15
17
  "content-changed",
16
18
  "unbound",
17
19
  "entry-superseded",
18
- "actor-not-allowed"
20
+ "actor-not-allowed",
21
+ "content-unhashable"
19
22
  ]);
20
23
  /** Only `human:` entries bind; machine entries neither bind nor break a binding. */
21
24
  const latestHumanOf = (entries) => entries.filter((entry) => Actor.isHuman(entry.by)).reduce((latest, entry) => latest === void 0 || DateTime.isGreaterThanOrEqualTo(entry.at, latest.at) ? entry : latest, void 0);
@@ -70,11 +73,31 @@ const signal = Effect.fn("Trust.signal")(function* (concept, config, now) {
70
73
  const tier = Derive.trustTier(concept.frontmatter);
71
74
  const stale = Derive.isStale(concept.frontmatter, now);
72
75
  const input = inputOf(concept, config);
73
- const content = needsDigest(input) ? yield* Derivation.contentDigest(concept.frontmatter.raw, concept.document.source) : void 0;
76
+ if (!needsDigest(input)) return {
77
+ tier,
78
+ stale,
79
+ ...evaluate(input, void 0)
80
+ };
81
+ const content = yield* Effect.result(Derivation.contentDigest(concept.frontmatter.raw, concept.document.source));
82
+ if (Result.isFailure(content)) {
83
+ const { detail, path } = content.failure;
84
+ return {
85
+ tier,
86
+ stale,
87
+ integrity: "drifted",
88
+ drift: {
89
+ reason: "content-unhashable",
90
+ unhashable: {
91
+ detail,
92
+ path
93
+ }
94
+ }
95
+ };
96
+ }
74
97
  return {
75
98
  tier,
76
99
  stale,
77
- ...evaluate(input, content)
100
+ ...evaluate(input, content.success)
78
101
  };
79
102
  });
80
103
  const signals = Effect.fn("Trust.signals")(function* (bundle, config, now) {
@@ -89,16 +112,18 @@ const messageFor = (concept, drift) => {
89
112
  if (drift.reason === "unbound") return `verified by ${by} at ${at}, but no integrity.verified binding records what was verified; re-run okfit verify`;
90
113
  if (drift.reason === "entry-superseded") return `the latest human verification (${by} at ${at}) is not the one integrity.verified binds; re-run okfit verify`;
91
114
  const binding = concept.frontmatter.integrity?.verified;
115
+ if (drift.reason === "content-unhashable") return `${drift.unhashable === void 0 || drift.unhashable.path.length === 0 ? "the frontmatter" : drift.unhashable.path.join(".")} cannot be hashed (${drift.unhashable?.detail ?? "not canonicalizable"}), so the verification by ${binding?.by ?? by} cannot be checked; fix the value, then re-run okfit verify`;
92
116
  if (drift.reason === "actor-not-allowed") return `verified by ${binding?.by ?? by}, who is not in [actors].humans; a listed human re-runs okfit verify`;
93
117
  const edited = drift.editedBy === void 0 ? "" : ` (edited by ${drift.editedBy} at ${drift.editedAt})`;
94
118
  return `content changed since ${binding?.by ?? by} verified it at ${binding === void 0 ? at : encodeAt(binding.at)}${edited}; re-run okfit verify`;
95
119
  };
96
120
  /**
97
- * Where a `verified-drift` finding points (spec section 6): the binding when one exists,
98
- * else the latest human `verified` entry -- by its list index when `verified` is a
121
+ * Where a `verified-drift` finding points (spec section 6): the offending value for
122
+ * `content-unhashable`, else the binding when one exists, else the latest human `verified` entry -- by its list index when `verified` is a
99
123
  * sequence, the key itself when it is a single bare mapping.
100
124
  */
101
- const rangePath = (concept) => {
125
+ const rangePath = (concept, drift) => {
126
+ if (drift.unhashable !== void 0 && drift.unhashable.path.length > 0) return drift.unhashable.path;
102
127
  if (concept.frontmatter.integrity?.verified !== void 0) return ["integrity", "verified"];
103
128
  const latest = latestHuman(concept);
104
129
  const index = latest === void 0 ? -1 : (concept.frontmatter.verified ?? []).indexOf(latest);
@@ -113,7 +138,7 @@ const lint = Effect.fn("Trust.lint")(function* (bundle, config, now, given) {
113
138
  if (status === "draft" || status === "deprecated") continue;
114
139
  const result = given?.get(id) ?? (yield* signal(concept, config, now));
115
140
  if (result.drift === void 0) continue;
116
- const range = DiagnosticRange.forFrontmatterPath(concept.document, rangePath(concept));
141
+ const range = DiagnosticRange.forFrontmatterPath(concept.document, rangePath(concept, result.drift));
117
142
  diagnostics.push(Diagnostic.make({
118
143
  file: concept.path,
119
144
  code: "verified-drift",
package/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
- import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
1
+ import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Result, Schema } from "effect";
2
2
  import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
3
3
  import { Actor, Diagnostic, DiagnosticRange, Digest, LoadedBundle, LoadedConcept, OkfitConfig, TrustTier } from "@okfit/core";
4
+ import { Digest as Digest$1 } from "effect/crypto";
4
5
  import { ChildProcessSpawner } from "effect/process";
5
6
  /**
6
7
  * The body is at HEAD and last changed in the commit described here (P-9).
@@ -58,6 +59,20 @@ export type BodyProvenance = typeof BodyProvenance.Type;
58
59
  * @public
59
60
  */
60
61
  type UncommittedReason = typeof BodyUncommitted.fields.reason.Type;
62
+ declare const ContentUnhashableError_base: Schema.Class<ContentUnhashableError, Schema.TaggedStruct<"ContentUnhashableError", {
63
+ readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
64
+ readonly detail: Schema.String;
65
+ }>, import("effect/Cause").YieldableError>;
66
+ /**
67
+ * A concept's content cannot be canonicalized for its digest, so it has none: most often a frontmatter
68
+ * string holding an unpaired surrogate (`"\uD800"`). `path` is the offending value's frontmatter path
69
+ * (`[]` for the frontmatter itself), `detail` the canonicalizer's reason.
70
+ *
71
+ * @public
72
+ */
73
+ export declare class ContentUnhashableError extends ContentUnhashableError_base {
74
+ get message(): string;
75
+ }
61
76
  /**
62
77
  * Canonical encoding for okfit's content digest.
63
78
  *
@@ -67,10 +82,8 @@ export declare class Canonical {
67
82
  private constructor();
68
83
  /** Top-level frontmatter keys excluded from the content digest. */
69
84
  static readonly EXCLUDED_KEYS: ReadonlySet<string>;
70
- /** Canonical JSON: sorted keys at every depth, array order kept; a `bigint` is its bare decimal literal. */
71
- static readonly json: (value: unknown) => string;
72
- /** The exact string a content digest hashes. */
73
- static readonly contentInput: (raw: Readonly<Record<string, unknown>>, source: string) => string;
85
+ /** The exact string a content digest hashes, or a {@link ContentUnhashableError}. */
86
+ static readonly contentInput: (raw: Readonly<Record<string, unknown>>, source: string) => Result.Result<string, ContentUnhashableError>;
74
87
  }
75
88
  declare const PathHistoryEntry_base: Schema.Class<PathHistoryEntry, Schema.Struct<{
76
89
  readonly sha: Schema.String;
@@ -284,17 +297,17 @@ export declare class Derivation {
284
297
  *
285
298
  * @internal
286
299
  */
287
- static readonly digestFull: (text: string) => Effect.Effect<string, PlatformError.PlatformError, Crypto.Crypto>;
300
+ static readonly digestFull: (text: string) => Effect.Effect<string, never, Digest$1.Digest>;
288
301
  /**
289
302
  * The okfit digest of a string: the first 16 lowercase hex characters of its SHA-256, through
290
- * `effect`'s platform-agnostic `Crypto` service.
303
+ * core's platform-agnostic `Digest` service.
291
304
  */
292
- static readonly digest: (text: string) => Effect.Effect<Digest, PlatformError.PlatformError, Crypto.Crypto>;
305
+ static readonly digest: (text: string) => Effect.Effect<Digest, never, Digest$1.Digest>;
293
306
  /**
294
307
  * 16-hex digest of `Derivation.body(source)` (issue #19). Same normalization as `body`, so a
295
308
  * frontmatter-only edit or a `core.autocrlf` worktree never changes the digest.
296
309
  */
297
- static readonly bodyDigest: (source: string) => Effect.Effect<Digest, PlatformError.PlatformError, Crypto.Crypto>;
310
+ static readonly bodyDigest: (source: string) => Effect.Effect<Digest, never, Digest$1.Digest>;
298
311
  /**
299
312
  * The body digest recorded for a generated concept: `integrity.generated.body`, else the legacy
300
313
  * `generated.body_sha256` cut to its first 16 hex characters. `undefined` when neither is present.
@@ -303,9 +316,10 @@ export declare class Derivation {
303
316
  static readonly recordedBody: (concept: LoadedConcept) => string | undefined;
304
317
  /**
305
318
  * 16-hex digest of the canonical content input (`Canonical.contentInput`): authored frontmatter
306
- * plus the normalised body, insensitive to style, key order and CRLF.
319
+ * plus the normalised body, insensitive to style, key order and CRLF. Fails with
320
+ * {@link ContentUnhashableError} when the content cannot be canonicalized (an unpaired surrogate).
307
321
  */
308
- static readonly contentDigest: (raw: Readonly<Record<string, unknown>>, source: string) => Effect.Effect<Digest, PlatformError.PlatformError, Crypto.Crypto>;
322
+ static readonly contentDigest: (raw: Readonly<Record<string, unknown>>, source: string) => Effect.Effect<Digest, ContentUnhashableError, Digest$1.Digest>;
309
323
  /**
310
324
  * Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
311
325
  * 1. `root = Git.repoRoot(dirname(file), { ignoreRepositoryEnv: true })`: the option drops the
@@ -548,7 +562,7 @@ export declare class Provenance {
548
562
  private constructor();
549
563
  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, options?: {
550
564
  readonly skipGitTier?: boolean;
551
- }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Crypto.Crypto>;
565
+ }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Digest$1.Digest>;
552
566
  }
553
567
  /**
554
568
  * The concept type name of a documentation surface.
@@ -588,7 +602,7 @@ export declare class Publications {
588
602
  /** The `renders` entries of a Publication, or `undefined` when malformed. */
589
603
  static readonly rendersOf: (concept: LoadedConcept) => ReadonlyArray<RendersEntry> | undefined;
590
604
  /** Lints every Publication in `bundle`; diagnostics are sorted by file then code. */
591
- static readonly lint: (bundle: LoadedBundle, config: OkfitConfig) => Effect.Effect<ReadonlyArray<Diagnostic>, PlatformError.PlatformError, Crypto.Crypto>;
605
+ static readonly lint: (bundle: LoadedBundle, config: OkfitConfig) => Effect.Effect<ReadonlyArray<Diagnostic>, PlatformError.PlatformError, Digest$1.Digest>;
592
606
  }
593
607
  /**
594
608
  * Whether a concept's human verification still covers its content: `none` (no
@@ -600,12 +614,14 @@ export declare class Publications {
600
614
  type IntegrityState = "current" | "drifted" | "none";
601
615
  /**
602
616
  * Why a human verification no longer binds: the content changed, the entry has
603
- * no `integrity.verified` binding, a later human entry is not the bound one, or
604
- * the bound actor fails a non-empty `[actors].humans` allow-list.
617
+ * no `integrity.verified` binding, a later human entry is not the bound one, the
618
+ * bound actor fails a non-empty `[actors].humans` allow-list, or the content
619
+ * cannot be hashed at all (an unpaired surrogate; okfit#327), so the binding
620
+ * cannot be checked.
605
621
  *
606
622
  * @public
607
623
  */
608
- export declare const DriftReason: Schema.Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
624
+ export declare const DriftReason: Schema.Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed", "content-unhashable"]>;
609
625
  /**
610
626
  * The type of {@link (DriftReason:variable)}.
611
627
  * @public
@@ -625,6 +641,11 @@ interface ConceptSignal {
625
641
  readonly reason: DriftReason;
626
642
  readonly editedBy?: Actor;
627
643
  readonly editedAt?: string;
644
+ /** For `content-unhashable`: why, and the offending frontmatter path. */
645
+ readonly unhashable?: {
646
+ readonly detail: string;
647
+ readonly path: ReadonlyArray<string | number>;
648
+ };
628
649
  };
629
650
  readonly stale: boolean;
630
651
  }
@@ -662,9 +683,9 @@ interface EvaluateInput {
662
683
  export declare class Trust {
663
684
  private constructor();
664
685
  /** The signal for one concept under `config`; hashes only when a human entry is bound by an allowed actor. */
665
- static readonly signal: (concept: LoadedConcept, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<ConceptSignal, PlatformError.PlatformError, Crypto.Crypto>;
686
+ static readonly signal: (concept: LoadedConcept, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<ConceptSignal, never, Digest$1.Digest>;
666
687
  /** The signal for every concept in a bundle, keyed by concept id. */
667
- static readonly signals: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<Map<string, ConceptSignal>, PlatformError.PlatformError, Crypto.Crypto>;
688
+ static readonly signals: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<Map<string, ConceptSignal>, never, Digest$1.Digest>;
668
689
  /** Pure integrity decision; no hashing. `content` may be `undefined` only when {@link Trust.needsDigest} is false. */
669
690
  static readonly evaluate: (input: EvaluateInput, content: string | undefined) => {
670
691
  readonly integrity: IntegrityState;
@@ -679,7 +700,7 @@ export declare class Trust {
679
700
  * Given `signals` (from {@link Trust.signals}) it reuses each concept's entry and hashes nothing for it;
680
701
  * a concept absent from `signals` falls back to computing its own signal (hashing if it needs a digest).
681
702
  */
682
- static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc, signals?: ReadonlyMap<string, ConceptSignal>) => Effect.Effect<Array<Diagnostic>, PlatformError.PlatformError, Crypto.Crypto>;
703
+ static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc, signals?: ReadonlyMap<string, ConceptSignal>) => Effect.Effect<Array<Diagnostic>, never, Digest$1.Digest>;
683
704
  }
684
705
  export type { ConceptSignal, DocsPreset, EvaluateInput, GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, IntegrityState, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, RendersEntry, SurfaceTemplate, UncommittedReason, VerifierError, Writer };
685
706
  //# sourceMappingURL=index.d.ts.map
package/index.js CHANGED
@@ -1,11 +1,11 @@
1
1
  import { BodyCommitted, BodyProvenance, BodyUncommitted } from "./BodyProvenance.js";
2
- import { Canonical } from "./Canonical.js";
3
- import { GitHistory, GitHistoryError, PathHistoryEntry } from "./GitHistory.js";
2
+ import { Canonical, ContentUnhashableError } from "./Canonical.js";
4
3
  import { ActorConfigInvalidError, AgentActorUnconfiguredError, Derivation, HumanActorNotAllowedError, HumanActorUnresolvedError } from "./Derivation.js";
4
+ import { GitHistory, GitHistoryError, PathHistoryEntry } from "./GitHistory.js";
5
5
  import { PROFILE_NAMES, ProfileDiagnostic, ProfileDiagnosticCode } from "./Profile.js";
6
6
  import { Profiles } from "./Profiles.js";
7
7
  import { Provenance } from "./Provenance.js";
8
8
  import { PUBLICATION_TYPE, Publications, SURFACE_TYPE } from "./Publications.js";
9
9
  import { DriftReason, Trust } from "./Trust.js";
10
10
 
11
- export { ActorConfigInvalidError, AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Canonical, Derivation, DriftReason, GitHistory, GitHistoryError, HumanActorNotAllowedError, HumanActorUnresolvedError, PROFILE_NAMES, PUBLICATION_TYPE, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance, Publications, SURFACE_TYPE, Trust };
11
+ export { ActorConfigInvalidError, AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Canonical, ContentUnhashableError, Derivation, DriftReason, GitHistory, GitHistoryError, HumanActorNotAllowedError, HumanActorUnresolvedError, PROFILE_NAMES, PUBLICATION_TYPE, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance, Publications, SURFACE_TYPE, Trust };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@okfit/profiles",
3
- "version": "0.13.0",
3
+ "version": "0.14.1",
4
4
  "private": false,
5
5
  "description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
6
6
  "keywords": [
@@ -35,14 +35,14 @@
35
35
  "./package.json": "./package.json"
36
36
  },
37
37
  "peerDependencies": {
38
- "@effected/git": "^0.27.0",
39
- "@effected/glob": "^0.16.0",
40
- "@effected/jsonc": "^0.21.0",
41
- "@effected/markdown": "^0.24.0",
42
- "@effected/source": "^0.1.0",
43
- "@effected/walker": "^0.22.0",
44
- "@okfit/core": "^0.11.8",
45
- "effect": "^4.0.0"
38
+ "@effected/git": "^0.30.0",
39
+ "@effected/glob": "^0.18.0",
40
+ "@effected/jsonc": "^0.23.0",
41
+ "@effected/markdown": "^0.26.0",
42
+ "@effected/source": "^0.3.0",
43
+ "@effected/walker": "^0.25.0",
44
+ "@okfit/core": "^0.12.1",
45
+ "effect": "~4.1.2"
46
46
  },
47
47
  "engines": {
48
48
  "node": ">=24.11.0"
@@ -5,7 +5,7 @@
5
5
  "toolPackages": [
6
6
  {
7
7
  "packageName": "@microsoft/api-extractor",
8
- "packageVersion": "7.60.0"
8
+ "packageVersion": "7.60.1"
9
9
  }
10
10
  ]
11
11
  }