@okfit/profiles 0.8.3 → 0.10.0

package/Trust.js

@@ -0,0 +1,156 @@
+import { Derivation } from "./Derivation.js";
+import { Actor, Derive, Diagnostic, DiagnosticRange, OkfitConfig, Timestamp } from "@okfit/core";
+import { DateTime, Effect, Schema } from "effect";
+
+//#region src/Trust.ts
+const encodeAt = Schema.encodeSync(Timestamp);
+/**
+* Why a human verification no longer binds: the content changed, the entry has
+* no `integrity.verified` binding, a later human entry is not the bound one, or
+* the bound actor fails a non-empty `[actors].humans` allow-list.
+*
+* @public
+*/
+const DriftReason = Schema.Literals([
+	"content-changed",
+	"unbound",
+	"entry-superseded",
+	"actor-not-allowed"
+]);
+/** Only `human:` entries bind; machine entries neither bind nor break a binding. */
+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);
+const latestHuman = (concept) => latestHumanOf(concept.frontmatter.verified ?? []);
+const inputOf = (concept, config) => ({
+	verified: concept.frontmatter.verified ?? [],
+	binding: concept.frontmatter.integrity?.verified,
+	generated: concept.frontmatter.generated,
+	humans: config.actors?.humans ?? []
+});
+/** The binding when it names the latest human entry; `undefined` when none, unbound or superseded. */
+const boundEntry = (input) => {
+	const latest = latestHumanOf(input.verified);
+	const binding = input.binding;
+	if (latest === void 0 || binding === void 0) return void 0;
+	return binding.by === latest.by && DateTime.Equivalence(binding.at, latest.at) ? binding : void 0;
+};
+const needsDigest = (input) => {
+	const bound = boundEntry(input);
+	return bound !== void 0 && Actor.allowed(bound.by, input.humans);
+};
+const evaluate = (input, content) => {
+	if (latestHumanOf(input.verified) === void 0) return { integrity: "none" };
+	const binding = input.binding;
+	if (binding === void 0) return {
+		integrity: "drifted",
+		drift: { reason: "unbound" }
+	};
+	if (boundEntry(input) === void 0) return {
+		integrity: "drifted",
+		drift: { reason: "entry-superseded" }
+	};
+	if (!Actor.allowed(binding.by, input.humans)) return {
+		integrity: "drifted",
+		drift: { reason: "actor-not-allowed" }
+	};
+	if (content === void 0) throw new Error("Trust.evaluate: a bound verification needs a content digest");
+	if (content === binding.content) return { integrity: "current" };
+	const generated = input.generated;
+	return {
+		integrity: "drifted",
+		drift: {
+			reason: "content-changed",
+			...generated?.at !== void 0 && DateTime.isGreaterThan(generated.at, binding.at) ? {
+				editedBy: generated.by,
+				editedAt: encodeAt(generated.at)
+			} : {}
+		}
+	};
+};
+const signal = Effect.fn("Trust.signal")(function* (concept, config, now) {
+	const tier = Derive.trustTier(concept.frontmatter);
+	const stale = Derive.isStale(concept.frontmatter, now);
+	const input = inputOf(concept, config);
+	const content = needsDigest(input) ? yield* Derivation.contentDigest(concept.frontmatter.raw, concept.document.source) : void 0;
+	return {
+		tier,
+		stale,
+		...evaluate(input, content)
+	};
+});
+const signals = Effect.fn("Trust.signals")(function* (bundle, config, now) {
+	const out = /* @__PURE__ */ new Map();
+	for (const [id, concept] of bundle.concepts) out.set(id, yield* signal(concept, config, now));
+	return out;
+});
+const messageFor = (concept, drift) => {
+	const latest = latestHuman(concept);
+	const by = latest?.by ?? "a human";
+	const at = latest === void 0 ? "an unknown time" : encodeAt(latest.at);
+	if (drift.reason === "unbound") return `verified by ${by} at ${at}, but no integrity.verified binding records what was verified; re-run okfit verify`;
+	if (drift.reason === "entry-superseded") return `the latest human verification (${by} at ${at}) is not the one integrity.verified binds; re-run okfit verify`;
+	const binding = concept.frontmatter.integrity?.verified;
+	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`;
+	const edited = drift.editedBy === void 0 ? "" : ` (edited by ${drift.editedBy} at ${drift.editedAt})`;
+	return `content changed since ${binding?.by ?? by} verified it at ${binding === void 0 ? at : encodeAt(binding.at)}${edited}; re-run okfit verify`;
+};
+/**
+* Where a `verified-drift` finding points (spec section 6): the binding when one exists,
+* else the latest human `verified` entry -- by its list index when `verified` is a
+* sequence, the key itself when it is a single bare mapping.
+*/
+const rangePath = (concept) => {
+	if (concept.frontmatter.integrity?.verified !== void 0) return ["integrity", "verified"];
+	const latest = latestHuman(concept);
+	const index = latest === void 0 ? -1 : (concept.frontmatter.verified ?? []).indexOf(latest);
+	return Array.isArray(concept.frontmatter.raw.verified) && index >= 0 ? ["verified", index] : ["verified"];
+};
+const lint = Effect.fn("Trust.lint")(function* (bundle, config, now, given) {
+	const severity = OkfitConfig.severityFor(config, "verified-drift");
+	if (severity === "off") return [];
+	const diagnostics = [];
+	for (const [id, concept] of bundle.concepts) {
+		const status = Derive.status(concept.frontmatter);
+		if (status === "draft" || status === "deprecated") continue;
+		const result = given?.get(id) ?? (yield* signal(concept, config, now));
+		if (result.drift === void 0) continue;
+		const range = DiagnosticRange.forFrontmatterPath(concept.document, rangePath(concept));
+		diagnostics.push(Diagnostic.make({
+			file: concept.path,
+			code: "verified-drift",
+			severity,
+			message: messageFor(concept, result.drift),
+			...range === void 0 ? {} : { range }
+		}));
+	}
+	return diagnostics;
+});
+/**
+* The integrity trust signal: whether a human verification still binds the
+* content it covered, and the `verified-drift` lint built on it. A signal, not
+* a tamper seal. Named `Trust` so it does not collide with core's `Integrity`
+* schema.
+*
+* @public
+*/
+var Trust = class {
+	constructor() {}
+	/** The signal for one concept under `config`; hashes only when a human entry is bound by an allowed actor. */
+	static signal = signal;
+	/** The signal for every concept in a bundle, keyed by concept id. */
+	static signals = signals;
+	/** Pure integrity decision; no hashing. `content` may be `undefined` only when {@link Trust.needsDigest} is false. */
+	static evaluate = evaluate;
+	/** True iff the latest human entry is bound by `integrity.verified` and its actor passes the allow-list, i.e. a digest is needed. */
+	static needsDigest = needsDigest;
+	/** The {@link EvaluateInput} of a loaded concept. */
+	static inputOf = inputOf;
+	/**
+	* `verified-drift` diagnostics for drifted concepts (drafts and deprecated concepts are exempt: `okfit verify` refuses them); `[]` (no hashing) when the severity is `off`.
+	* Given `signals` (from {@link Trust.signals}) it reuses each concept's entry and hashes nothing for it;
+	* a concept absent from `signals` falls back to computing its own signal (hashing if it needs a digest).
+	*/
+	static lint = lint;
+};
+
+//#endregion
+export { DriftReason, Trust };

package/index.d.ts

@@ -1,6 +1,6 @@
 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 { Actor, Diagnostic, DiagnosticRange, Digest, LoadedBundle, LoadedConcept, OkfitConfig, TrustTier } from "@okfit/core";
 import { ChildProcessSpawner } from "effect/process";
 //#region src/BodyProvenance.d.ts
 /**
@@ -60,6 +60,22 @@ export type BodyProvenance = typeof BodyProvenance.Type;
  */
 type UncommittedReason = typeof BodyUncommitted.fields.reason.Type;
 //#endregion
+//#region src/Canonical.d.ts
+/**
+ * Canonical encoding for okfit's content digest.
+ *
+ * @public
+ */
+export declare class Canonical {
+  private constructor();
+  /** Top-level frontmatter keys excluded from the content digest. */
+  static readonly EXCLUDED_KEYS: ReadonlySet<string>;
+  /** Canonical JSON: sorted keys at every depth, array order kept; a `bigint` is its bare decimal literal. */
+  static readonly json: (value: unknown) => string;
+  /** The exact string a content digest hashes. */
+  static readonly contentInput: (raw: Readonly<Record<string, unknown>>, source: string) => string;
+}
+//#endregion
 //#region src/GitHistory.d.ts
 declare const PathHistoryEntry_base: Schema.Class<PathHistoryEntry, Schema.Struct<{
   readonly sha: Schema.String;
@@ -178,6 +194,31 @@ declare const AgentActorUnconfiguredError_base: Schema.Class<AgentActorUnconfigu
 export declare class AgentActorUnconfiguredError extends AgentActorUnconfiguredError_base {
   get message(): string;
 }
+declare const ActorConfigInvalidError_base: Schema.Class<ActorConfigInvalidError, Schema.TaggedStruct<"ActorConfigInvalidError", {
+  readonly value: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `git config okfit.actor` is set but is not a `human:<id>` actor without `@`
+ * or glob characters. The value stays on the person's machine; okfit never
+ * writes it anywhere.
+ *
+ * @public
+ */
+export declare class ActorConfigInvalidError extends ActorConfigInvalidError_base {
+  get message(): string;
+}
+declare const HumanActorNotAllowedError_base: Schema.Class<HumanActorNotAllowedError, Schema.TaggedStruct<"HumanActorNotAllowedError", {
+  readonly actor: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The resolved human is not on a non-empty `[actors].humans` allow-list, so it
+ * may not verify or revoke (spec section 8).
+ *
+ * @public
+ */
+export declare class HumanActorNotAllowedError extends HumanActorNotAllowedError_base {
+  get message(): string;
+}
 /**
  * Options for {@link Derivation.generatedAt} (P-39).
  *
@@ -214,7 +255,13 @@ interface GeneratedByOptions {
  *
  * @public
  */
-type GeneratedByError = AgentActorUnconfiguredError | HumanActorUnresolvedError | GitCommandError | NotARepositoryError | UnknownRefError;
+type GeneratedByError = ActorConfigInvalidError | AgentActorUnconfiguredError | HumanActorUnresolvedError | GitCommandError | NotARepositoryError | UnknownRefError;
+/**
+ * Everything {@link Derivation.verifier} can fail with.
+ *
+ * @public
+ */
+type VerifierError = GeneratedByError | HumanActorNotAllowedError;
 /**
  * Trimmed `user.name` / `user.email` as `Git.configGet` answers them; a key is absent when git has no value.
  *
@@ -240,11 +287,32 @@ export declare class Derivation {
    */
   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.
+   * Full lowercase 64-char hex sha256 of a string. Tests only.
+   *
+   * @internal
    */
-  static readonly bodyDigest: (text: string) => Effect.Effect<string, PlatformError.PlatformError, Crypto.Crypto>;
+  static readonly digestFull: (text: string) => Effect.Effect<string, PlatformError.PlatformError, Crypto.Crypto>;
+  /**
+   * The okfit digest of a string: the first 16 lowercase hex characters of its SHA-256, through
+   * `effect`'s platform-agnostic `Crypto` service.
+   */
+  static readonly digest: (text: string) => Effect.Effect<Digest, PlatformError.PlatformError, Crypto.Crypto>;
+  /**
+   * 16-hex digest of `Derivation.body(source)` (issue #19). Same normalization as `body`, so a
+   * frontmatter-only edit or a `core.autocrlf` worktree never changes the digest.
+   */
+  static readonly bodyDigest: (source: string) => Effect.Effect<Digest, PlatformError.PlatformError, Crypto.Crypto>;
+  /**
+   * The body digest recorded for a generated concept: `integrity.generated.body`, else the legacy
+   * `generated.body_sha256` cut to its first 16 hex characters. `undefined` when neither is present.
+   * Pure; every "is the stamped body still current" comparison reads through this.
+   */
+  static readonly recordedBody: (concept: LoadedConcept) => string | undefined;
+  /**
+   * 16-hex digest of the canonical content input (`Canonical.contentInput`): authored frontmatter
+   * plus the normalised body, insensitive to style, key order and CRLF.
+   */
+  static readonly contentDigest: (raw: Readonly<Record<string, unknown>>, source: string) => Effect.Effect<Digest, 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`;
@@ -265,18 +333,30 @@ export declare class Derivation {
   static readonly generatedAt: (options: GeneratedAtOptions) => Effect.Effect<BodyProvenance, GeneratedAtError, Git | GitHistory | FileSystem.FileSystem | Path.Path>;
   /**
    * P-13 / P-14, pure. Candidates: the email local part (returned as written, lower-cased only for matching)
-   * and the `user.name` slug. Order, first hit wins: (1) a `human:` entry of `humans` whose id equals a
-   * candidate case-insensitively, returned verbatim; (2) `human:<local>`; (3) `human:<slug>`; (4) none.
+   * and the `user.name` slug. Order, first hit wins: (1) a literal `human:` entry of `humans` (glob entries,
+   * those with `*` or `?`, are skipped) whose id equals a candidate case-insensitively, returned verbatim; (2) `human:<local>`; (3) `human:<slug>`; (4) none.
    * The result is branded through core's `Actor` codec and always passes it.
    */
-  static readonly humanActorId: (identity: GitIdentity, humans: ReadonlyArray<Actor>) => Option.Option<Actor>;
+  static readonly humanActorId: (identity: GitIdentity, humans: ReadonlyArray<string>) => Option.Option<Actor>;
   /**
    * Spec 5.4 rule 1 (P-16, P-45). `"agent"`: `config.actors.agent`, else {@link AgentActorUnconfiguredError}
-   * (P-17). `"human"`: `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` in merged
+   * (P-17). `"human"`: first `Git.configGet(cwd, "okfit.actor")`, which wins when set and must be a
+   * `human:<id>` with no `@` or glob ({@link ActorConfigInvalidError} otherwise), returned in the spelling of an exact `[actors].humans` entry that equals it case-insensitively (P-14); else `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` in merged
    * scope (P-15) through {@link Derivation.humanActorId}; none is {@link HumanActorUnresolvedError}.
    * Answers only "who is writing now" (P-40).
    */
   static readonly generatedBy: (options: GeneratedByOptions) => Effect.Effect<Actor, GeneratedByError, Git>;
+  /**
+   * The human allowed to verify now: {@link Derivation.generatedBy} for a human
+   * writer, then the `[actors].humans` allow-list (`Actor.allowed`): empty or
+   * absent allows anyone, otherwise the actor must match an entry or this fails
+   * {@link HumanActorNotAllowedError}. `okfit verify`, `--revoke` and the LSP
+   * verify actions all resolve through this.
+   */
+  static readonly verifier: (options: {
+    readonly cwd: string;
+    readonly config: OkfitConfig;
+  }) => Effect.Effect<Actor, VerifierError, Git>;
   /**
    * P-19, pure: `from` plus `config.lifecycle.default_stale_after`, falling back to `OkfitConfig.DEFAULTS`'
    * 90 days. `from` is the caller's: `generated.at` when committed, else its own `now`.
@@ -354,6 +434,41 @@ export declare const ProfileDiagnostic: Schema.Struct<{
  * @public
  */
 export type ProfileDiagnostic = typeof ProfileDiagnostic.Type;
+/**
+ * One Surface concept a docs preset writes: a bundle-relative `file` and the
+ * frontmatter and body to write there. `resource` is relative to the file.
+ * The `site` preset's `url` is an `https://example.invalid` placeholder the
+ * docs skill replaces.
+ *
+ * @public
+ */
+interface SurfaceTemplate {
+  readonly file: string;
+  readonly frontmatter: {
+    readonly type: "Surface";
+    readonly status: "draft";
+    readonly title: string;
+    readonly description: string;
+    readonly kind: "site" | "repo" | "readme";
+    readonly audience: "users" | "contributors" | "agents";
+    readonly resource: string;
+    readonly links_to?: string;
+    readonly url?: string;
+  };
+  readonly body: string;
+}
+/**
+ * A named set of Surface templates for one repository shape. `additive` is
+ * true only for `site`, which layers on another preset instead of replacing it.
+ *
+ * @public
+ */
+interface DocsPreset {
+  readonly name: "npm-package" | "monorepo-router" | "monorepo-shared-docs" | "site";
+  readonly description: string;
+  readonly additive: boolean;
+  readonly surfaces: ReadonlyArray<SurfaceTemplate>;
+}
 /**
  * A named profile (P-38): a partial `OkfitConfig` the CLI merges as
  * `DEFAULTS < profile < file`, a scaffolding `Layout`, and a pure `check`
@@ -365,6 +480,7 @@ interface Profile {
   readonly name: ProfileName;
   readonly config: OkfitConfig;
   readonly layout: Layout;
+  readonly docsPresets: ReadonlyArray<DocsPreset>;
   readonly check: (bundle: LoadedBundle) => ReadonlyArray<ProfileDiagnostic>;
 }
 //#endregion
@@ -395,17 +511,20 @@ export declare class Profiles {
  * like every other lint (S-7). `Profile.check` and `ProfileDiagnosticCode`
  * are unchanged.
  *
- * Two tiers per concept (issue #19, body-digest design): when
- * `generated.body_sha256` is present, drift is decided ENTIRELY by comparing it to
+ * Two tiers per concept (issue #19, body-digest design): when a body digest
+ * is recorded (`integrity.generated.body`, else the 16-hex prefix of a legacy
+ * `generated.body_sha256`, via `Derivation.recordedBody`), 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
+ * itself, and therefore its digest, never changed. When no digest is recorded
+ * at all (a concept `okfit sync` has never stamped), 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.
+ * since the digest was introduced. The drift message names the field the
+ * recorded value came from, so a legacy concept reads `generated.body_sha256`.
  *
  * The tier-2 fallback returns `[]` the moment a `NotARepositoryError`
  * surfaces: a bundle outside git has nothing to derive for any concept still
@@ -423,8 +542,8 @@ export declare class Profiles {
  * 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
+ * concept that falls through to tier 2 (no body digest 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
@@ -442,5 +561,140 @@ export declare class Provenance {
   }) => 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 };
+//#region src/Publications.d.ts
+/**
+ * The concept type name of a documentation surface.
+ *
+ * @public
+ */
+export declare const SURFACE_TYPE: "Surface";
+/**
+ * The concept type name of a published page rendered from bundle concepts.
+ *
+ * @public
+ */
+export declare const PUBLICATION_TYPE: "Publication";
+/**
+ * One entry of a Publication's `renders` list, with its position.
+ *
+ * @public
+ */
+interface RendersEntry {
+  readonly index: number;
+  readonly path: string;
+  readonly body?: string;
+}
+/**
+ * A profiles-owned lint over Publication concepts: `publication-orphan` when a
+ * `surface` or `renders[].path` does not resolve to a bundle concept (or
+ * `renders` is malformed), and `publication-drift` when a rendered source's
+ * body digest no longer matches the stamped `renders[].body`. Total over
+ * severity: returns `[]` before any digest work when both codes are `"off"`.
+ *
+ * @public
+ */
+export declare class Publications {
+  private constructor();
+  /** Resolves a raw reference against a bundle-relative concept path; `""` when it escapes the bundle. */
+  static readonly resolveRef: (from: string, raw: string) => string;
+  /** The `renders` entries of a Publication, or `undefined` when malformed. */
+  static readonly rendersOf: (concept: LoadedConcept) => ReadonlyArray<RendersEntry> | undefined;
+  /** Lints every Publication in `bundle`; diagnostics are sorted by file then code. */
+  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig) => Effect.Effect<ReadonlyArray<Diagnostic>, PlatformError.PlatformError, Crypto.Crypto>;
+}
+//#endregion
+//#region src/Trust.d.ts
+/**
+ * Whether a concept's human verification still covers its content: `none` (no
+ * `human:` entry in `verified`), `current` (the latest human entry is bound by
+ * `integrity.verified` and the content digest still matches), or `drifted`.
+ *
+ * @public
+ */
+type IntegrityState = "current" | "drifted" | "none";
+/**
+ * Why a human verification no longer binds: the content changed, the entry has
+ * no `integrity.verified` binding, a later human entry is not the bound one, or
+ * the bound actor fails a non-empty `[actors].humans` allow-list.
+ *
+ * @public
+ */
+export declare const DriftReason: Schema.Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
+/**
+ * The type of {@link (DriftReason:variable)}.
+ * @public
+ */
+export type DriftReason = typeof DriftReason.Type;
+/**
+ * The trust signal for one concept: its tier, whether its human verification
+ * still binds, and staleness. `drift` is present only when `integrity` is
+ * `drifted`.
+ *
+ * @public
+ */
+interface ConceptSignal {
+  readonly tier: TrustTier;
+  readonly integrity: IntegrityState;
+  readonly drift?: {
+    readonly reason: DriftReason;
+    readonly editedBy?: Actor;
+    readonly editedAt?: string;
+  };
+  readonly stale: boolean;
+}
+/**
+ * What the integrity decision reads from a concept: its `verified` entries, the
+ * `integrity.verified` binding, and `generated`. Built by {@link Trust.inputOf}.
+ *
+ * @public
+ */
+interface EvaluateInput {
+  readonly verified: ReadonlyArray<{
+    readonly by: Actor;
+    readonly at: DateTime.Utc;
+  }>;
+  readonly binding: {
+    readonly by: Actor;
+    readonly at: DateTime.Utc;
+    readonly content: string;
+  } | undefined;
+  readonly generated: {
+    readonly by: Actor;
+    readonly at?: DateTime.Utc;
+  } | undefined;
+  /** The `[actors].humans` allow-list; empty allows anyone. */
+  readonly humans: ReadonlyArray<string>;
+}
+/**
+ * The integrity trust signal: whether a human verification still binds the
+ * content it covered, and the `verified-drift` lint built on it. A signal, not
+ * a tamper seal. Named `Trust` so it does not collide with core's `Integrity`
+ * schema.
+ *
+ * @public
+ */
+export declare class Trust {
+  private constructor();
+  /** The signal for one concept under `config`; hashes only when a human entry is bound by an allowed actor. */
+  static readonly signal: (concept: LoadedConcept, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<ConceptSignal, PlatformError.PlatformError, Crypto.Crypto>;
+  /** The signal for every concept in a bundle, keyed by concept id. */
+  static readonly signals: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<Map<string, ConceptSignal>, PlatformError.PlatformError, Crypto.Crypto>;
+  /** Pure integrity decision; no hashing. `content` may be `undefined` only when {@link Trust.needsDigest} is false. */
+  static readonly evaluate: (input: EvaluateInput, content: string | undefined) => {
+    readonly integrity: IntegrityState;
+    readonly drift?: NonNullable<ConceptSignal["drift"]>;
+  };
+  /** True iff the latest human entry is bound by `integrity.verified` and its actor passes the allow-list, i.e. a digest is needed. */
+  static readonly needsDigest: (input: EvaluateInput) => boolean;
+  /** The {@link EvaluateInput} of a loaded concept. */
+  static readonly inputOf: (concept: LoadedConcept, config: OkfitConfig) => EvaluateInput;
+  /**
+   * `verified-drift` diagnostics for drifted concepts (drafts and deprecated concepts are exempt: `okfit verify` refuses them); `[]` (no hashing) when the severity is `off`.
+   * Given `signals` (from {@link Trust.signals}) it reuses each concept's entry and hashes nothing for it;
+   * a concept absent from `signals` falls back to computing its own signal (hashing if it needs a digest).
+   */
+  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc, signals?: ReadonlyMap<string, ConceptSignal>) => Effect.Effect<Array<Diagnostic>, PlatformError.PlatformError, Crypto.Crypto>;
+}
+//#endregion
+export type { ConceptSignal, DocsPreset, EvaluateInput, GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, IntegrityState, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, RendersEntry, SurfaceTemplate, UncommittedReason, VerifierError, Writer };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,8 +1,11 @@
 import { BodyCommitted, BodyProvenance, BodyUncommitted } from "./BodyProvenance.js";
+import { Canonical } from "./Canonical.js";
 import { GitHistory, GitHistoryError, PathHistoryEntry } from "./GitHistory.js";
-import { AgentActorUnconfiguredError, Derivation, HumanActorUnresolvedError } from "./Derivation.js";
+import { ActorConfigInvalidError, AgentActorUnconfiguredError, Derivation, HumanActorNotAllowedError, HumanActorUnresolvedError } from "./Derivation.js";
 import { PROFILE_NAMES, ProfileDiagnostic, ProfileDiagnosticCode } from "./Profile.js";
 import { Profiles } from "./Profiles.js";
 import { Provenance } from "./Provenance.js";
+import { PUBLICATION_TYPE, Publications, SURFACE_TYPE } from "./Publications.js";
+import { DriftReason, Trust } from "./Trust.js";
 
-export { AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Derivation, GitHistory, GitHistoryError, HumanActorUnresolvedError, PROFILE_NAMES, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance };
+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 };

package/internal/body.js

@@ -0,0 +1,13 @@
+import { FrontmatterSource } from "@effected/markdown";
+
+//#region src/internal/body.ts
+const normalise = (text) => text.replace(/\r\n?/g, "\n").trimEnd();
+/**
+* The normalised body of a concept source (`FrontmatterSource.split(text).body`, then P-6 normalisation).
+*
+* @internal
+*/
+const body = (text) => normalise(FrontmatterSource.split(text).body);
+
+//#endregion
+export { body };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/profiles",
-	"version": "0.8.3",
+	"version": "0.10.0",
 	"private": false,
 	"description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
 	"keywords": [
@@ -35,9 +35,9 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/git": "^0.20.0",
-		"@effected/markdown": "^0.15.0",
-		"@okfit/core": "^0.8.4",
+		"@effected/git": "^0.21.0",
+		"@effected/markdown": "^0.16.0",
+		"@okfit/core": "^0.10.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {

package/presets/index.js

@@ -0,0 +1,51 @@
+import { CONTRIBUTOR_GUIDES, DOCS_PACKAGE, DOCS_PACKAGES, DOCS_REPO, README_PACKAGE, README_PACKAGES, README_PACKAGES_ONE_PAGE, README_PACKAGE_ONE_PAGE, README_ROOT, README_ROOT_ONE_PAGE, SITE } from "./surfaces.js";
+
+//#region src/presets/index.ts
+/**
+* The docs-surface presets the `software-project` profile offers, one per
+* repository shape. Three replace a repository's surfaces; `site` is
+* additive and swaps the README templates for one-page variants that link to
+* the site.
+*
+* @public
+*/
+const DOCS_PRESETS = [
+	{
+		name: "npm-package",
+		description: "A single package published to npm: a README surface that links to a docs/ folder surface.",
+		additive: false,
+		surfaces: [README_PACKAGE, DOCS_PACKAGE]
+	},
+	{
+		name: "monorepo-router",
+		description: "A monorepo whose root README routes to per-package READMEs.",
+		additive: false,
+		surfaces: [README_ROOT, README_PACKAGES]
+	},
+	{
+		name: "monorepo-shared-docs",
+		description: "A monorepo with routing READMEs plus a shared root docs/ folder, contributor guides and per-package docs/ folders read on the forge.",
+		additive: false,
+		surfaces: [
+			README_ROOT,
+			README_PACKAGES,
+			DOCS_REPO,
+			DOCS_PACKAGES,
+			CONTRIBUTOR_GUIDES
+		]
+	},
+	{
+		name: "site",
+		description: "A documentation website plus one-page README variants that link to it; keep the variants that match the repository shape.",
+		additive: true,
+		surfaces: [
+			SITE,
+			README_ROOT_ONE_PAGE,
+			README_PACKAGES_ONE_PAGE,
+			README_PACKAGE_ONE_PAGE
+		]
+	}
+];
+
+//#endregion
+export { DOCS_PRESETS };