@okfit/engine 0.1.0

package/index.d.ts

@@ -0,0 +1,957 @@
+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 { AppDirs, Xdg } from "@effected/xdg";
+import { ConfigReadError } from "@effected/config-file";
+import { GeneratedAtError, GitHistory, GitHistoryError, Layout, Profile, ProfileDiagnostic } from "@okfit/profiles";
+import { FrontmatterWriteError, MarkdownParseError } from "@effected/markdown";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Git, GitCommandError, UnknownRefError } from "@effected/git";
+//#region src/config/anchor.d.ts
+/**
+ * What {@link resolveProjectRoot} needs about the winning discovery source
+ * (K-12, K-58). Narrower than `@effected/config-file`'s own
+ * `ConfigSource`: only `path`, `resolver` and the match's `dir` matter for
+ * anchoring, and a caller building this from a real
+ * `ConfigSource<OkfitConfig>` simply drops `value`.
+ *
+ * @public
+ */
+interface DiscoveredConfig {
+  /** `ConfigSource.path` — absolute. */
+  readonly path: string;
+  /** `ConfigSource.resolver` — the resolver's `name`. */
+  readonly resolver: string;
+  /**
+   * `ConfigSource.match?.dir` — the ancestor directory `upwardWalk`
+   * anchored the winning candidate against. Absent when the resolver did
+   * not implement `resolveMatch`, or reported no `dir` (`explicitPath`
+   * never does, by design).
+   */
+  readonly dir?: string;
+}
+/**
+ * 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.
+ * 2. otherwise, if `--config` was given: `anchorForExplicit` applied to that
+ *    path.
+ * 3. otherwise, if a config was discovered by the `"project"` resolver
+ *    (`ConfigResolver.upwardWalk`, named `"project"` in `layer.ts`) AND it
+ *    reported a `dir`: that `dir` verbatim — it is already the ancestor
+ *    `upwardWalk` anchored the match against (the parent of `.config` for a
+ *    `.config/okfit.toml` candidate, the candidate's own directory
+ *    otherwise), so no path-tail test is needed here any more.
+ * 4. otherwise `cwd` — this covers every other resolver name (`"xdg"`,
+ *    `"native"`, `"system"`) as defence in depth, a `"project"` match with no
+ *    `dir` (should not happen, since `upwardWalk` always reports one), and
+ *    no discovery at all.
+ *
+ * The CLI never probes for `.git` (K-12), even though
+ * `ConfigResolver.gitRoot` exists.
+ *
+ * @public
+ */
+export declare const resolveProjectRoot: (input: {
+  readonly pathArg: Option.Option<string>;
+  readonly explicitConfigPath: Option.Option<string>;
+  readonly discovered: Option.Option<DiscoveredConfig>;
+  readonly cwd: string;
+  readonly path: Path.Path;
+}) => string;
+/**
+ * `<project root>/<bundle.path>`, absolute (K-2). `config` is the MERGED
+ * config, so `bundle.path` is `OkfitConfig.DEFAULTS.bundle.path` (`"okf"`)
+ * unless a file or profile overrode it. The bundle root is never what
+ * `[path]` names.
+ *
+ * @public
+ */
+export declare const resolveBundleRoot: (projectRoot: string, config: OkfitConfig, path: Path.Path) => string;
+//#endregion
+//#region src/errors.d.ts
+declare const ConfigPathNotFoundError_base: Schema.Class<ConfigPathNotFoundError, Schema.TaggedStruct<"ConfigPathNotFoundError", {
+  readonly path: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `--config <path>` named a path that does not exist. Every `ConfigResolver`
+ * has a `never` error channel and `explicitPath` absorbs a missing target
+ * into `Option.none()`, so a bad `--config` would otherwise fall through to
+ * the XDG file silently. The CLI checks it itself before building any layer
+ * (K-1, spec 4.1).
+ *
+ * @public
+ */
+export declare class ConfigPathNotFoundError extends ConfigPathNotFoundError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const InitOverwriteError_base: Schema.Class<InitOverwriteError, Schema.TaggedStruct<"InitOverwriteError", {
+  readonly paths: Schema.$Array<Schema.String>;
+  readonly cwd: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `okfit init` found one or more of its target paths already present (K-28).
+ * Carries the whole conflicting-path list so the renderer prints every one.
+ * `paths` are absolute; `renderFailure` relativises them to `cwd` (K-51).
+ *
+ * @public
+ */
+export declare class InitOverwriteError extends InitOverwriteError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const VerifyConceptNotFoundError_base: Schema.Class<VerifyConceptNotFoundError, Schema.TaggedStruct<"VerifyConceptNotFoundError", {
+  readonly id: Schema.String;
+  readonly root: Schema.String;
+  readonly reason: Schema.Literals<readonly ["not-a-concept", "reserved", "undecodable"]>;
+  readonly diagnosticCode: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * V-9: `<id>` did not resolve to a verifiable concept. `reason` is
+ * `"not-a-concept"` (no such file, or an id that normalises to nothing),
+ * `"reserved"` (the id names `index.md` or `log.md`), or `"undecodable"`
+ * (a file exists but `bundle.diagnostics` names it — `diagnosticCode`
+ * carries which). `root` is the absolute bundle root, kept OFF `message`
+ * so K-51's relativisation rule has nothing to apply to and the human
+ * line and the JSON envelope's `message` are identical.
+ *
+ * @public
+ */
+export declare class VerifyConceptNotFoundError extends VerifyConceptNotFoundError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const VerifyUnsupportedFrontmatterError_base: Schema.Class<VerifyUnsupportedFrontmatterError, Schema.TaggedStruct<"VerifyUnsupportedFrontmatterError", {
+  readonly id: Schema.String;
+  readonly shape: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * V-14: fail closed on a `verified` shape the classifier does not name.
+ * `shape` is one of `"alias"`, `"merge-key"`, `"scalar"`, `"empty"` (and,
+ * defensively, `"no-frontmatter"` or `"not-a-mapping"`, neither reachable
+ * for a concept that reached `bundle.concepts`). The file is never opened
+ * for writing when this is raised.
+ *
+ * @public
+ */
+export declare class VerifyUnsupportedFrontmatterError extends VerifyUnsupportedFrontmatterError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+declare const ConfigMalformedError_base: Schema.Class<ConfigMalformedError, Schema.TaggedStruct<"ConfigMalformedError", {
+  readonly path: Schema.String;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A config file at a KNOWN path failed to parse or validate (K-46's own
+ * intent — "each class' message already names the offending path" does not
+ * hold for `@effected/config-file`'s `ConfigCodecError`, which carries no
+ * `path` field at all; this wraps it, and `ConfigValidationError`, with the
+ * path the caller already knows). `cause` is the original config-file error,
+ * preserved structurally, never stringified early.
+ *
+ * @public
+ */
+export declare class ConfigMalformedError extends ConfigMalformedError_base {
+  readonly [Runtime.errorExitCode] = 3;
+  get message(): string;
+}
+//#endregion
+//#region src/config/layer.d.ts
+/**
+ * The `OkfitConfigFile` layer for one invocation (K-9 to K-11, K-57, C-6),
+ * now one `AppConfig.layer(OkfitConfigFile, ...)` call in both branches; only
+ * the chain options vary:
+ *
+ * - `explicitConfigPath` is `Some`: `resolvers: [ConfigResolver.explicitPath(path)]`
+ *   and `xdg: false` — K-10's "only that path" rule, so the chain is exactly
+ *   one resolver and no `systemEtc` tier is added either.
+ * - `explicitConfigPath` is `None`: `resolvers: [ConfigResolver.upwardWalk({ filenames, ... })]`
+ *   carrying C-1's three per-directory candidates (`.okfit.toml`,
+ *   `okfit.toml`, `.config/okfit.toml`, directory-major so a child's later
+ *   candidate beats a parent's earlier one — C-2's ascent to the filesystem
+ *   root is `upwardWalk`'s own default with no `stopAt`), named `"project"`
+ *   so `resolve.ts`/`anchor.ts` can identify it without string-matching a
+ *   path tail. `systemEtc` is C-5's `/etc` tier, present unless
+ *   `systemConfigDir` overrides its root (tests only — no production call
+ *   site sets it). `xdg` and `native` stay on their defaults (C-4), which is
+ *   what puts personal defaults at `$XDG_CONFIG_HOME/okfit/config.toml` and
+ *   the native probe behind it.
+ *
+ * `filename: "config.toml"` is the same in both branches — it is the XDG/
+ * native/system tiers' filename, unrelated to the C-1 project names above.
+ * `defaultPath` is `AppConfig.layer`'s own `XdgConfig.savePath(filename)`, so
+ * `save`/`update` do not fail with `ConfigDefaultPathMissingError`; nothing
+ * here sets it explicitly any more.
+ *
+ * `discoveryCwd` is `[path]` when given, else `process.cwd()` (K-2), passed
+ * straight through as `upwardWalk`'s own `cwd` so nothing in this module
+ * reads the process.
+ *
+ * `App.layer`, `AppStore` and `AppCache` appear nowhere, so no
+ * `store.db`/`cache.db` is ever created (K-9).
+ *
+ * @public
+ */
+export declare const buildConfigLayer: (options: {
+  readonly explicitConfigPath: Option.Option<string>;
+  readonly discoveryCwd: string;
+  /**
+   * System config root, defaulting to `/etc`. Overridable primarily so tests
+   * can point at a writable temp directory — the real `/etc` is not writable
+   * in test environments. No production call site sets it.
+   */
+  readonly systemConfigDir?: string;
+}) => Layer.Layer<OkfitConfigFile, never, FileSystem.FileSystem | Path.Path | AppDirs | Xdg>;
+/**
+ * The K-1 pre-flight and the provide, in that order and in one place: stat
+ * `explicitConfigPath` with `FileSystem.exists` and fail with
+ * `ConfigPathNotFoundError` BEFORE `buildConfigLayer` is called at all. This
+ * is why the CLI does not use `Command.provide(cmd, (input) => layer)`,
+ * which would construct the layer first (Judge notes 9) — here the stat
+ * runs as the first step of one `Effect.gen`, and `buildConfigLayer` is only
+ * reached, and only then actually run, on the step after it.
+ *
+ * `FileSystem.FileSystem.exists` is `(path: string) => Effect.Effect<boolean, PlatformError>`
+ * (`EF/FileSystem.ts:143-145`), not infallible, so
+ * `PlatformError.PlatformError` joins the error channel here (decision 7):
+ * an unusual stat failure (e.g. a permission error on a parent directory)
+ * renders through `renderFailure`'s catch-all rule rather than being
+ * uncatchable by the type checker.
+ *
+ * K-46/K-63 fix: a `ConfigCodecError`/`ConfigValidationError` from
+ * `buildConfigLayer`'s provided layer is wrapped into `ConfigMalformedError`
+ * whenever the failing path is known, so `renderFailure` can name it:
+ *
+ * - `ConfigCodecError` now carries its own `path: string | undefined`
+ *   (config-file 0.7.0, `ConfigFile.discover` re-raises with `path` attached
+ *   at every site that fed the codec a path it resolved) — used when
+ *   present, so a malformed file found during DISCOVERY (no `--config`) now
+ *   also wraps into `ConfigMalformedError` naming the candidate that failed,
+ *   closing the K-63 gap. It falls back to `explicitConfigPath` only when
+ *   the library's own `path` is `undefined` and `--config` was given; only
+ *   when neither is known does the cause pass through unwrapped.
+ * - `ConfigValidationError` carries its own `path: Option<string>` — used
+ *   when present (either branch), falling back to `explicitConfigPath` when
+ *   the library's own `path` is `None` and `--config` was given.
+ *
+ * @public
+ */
+export declare const provideConfig: (options: {
+  readonly explicitConfigPath: Option.Option<string>;
+  readonly discoveryCwd: string;
+  readonly systemConfigDir?: string;
+}) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | ConfigPathNotFoundError | ConfigMalformedError | PlatformError.PlatformError, Exclude<R, OkfitConfigFile> | FileSystem.FileSystem | Path.Path | AppDirs | Xdg>;
+//#endregion
+//#region src/config/resolve.d.ts
+/**
+ * `OkfitConfig.DEFAULTS.bundle.profile` is `"software-project"` at runtime
+ * (the frozen literal always sets it), but `bundle` and `profile` are both
+ * `optionalKey` in the schema, so the type checker sees `string | undefined`
+ * two levels deep. The `?? "software-project"` fallback here is unreachable
+ * in practice; it exists only to satisfy `noUncheckedIndexedAccess`-style
+ * strictness without a non-null assertion. Formerly duplicated identically
+ * in `commands/validate.ts` and `commands/context.ts`; this is its one home
+ * now that both commands delegate to {@link resolveProjectConfig}.
+ *
+ * @public
+ */
+export declare const DEFAULT_PROFILE_NAME: string;
+/**
+ * Everything `validate` and `context`'s handlers derive from config
+ * discovery before diverging (contract §8.3): the merged config, the
+ * resolved profile (and its name after the "none"/default rule), the
+ * discovery source (if any), and the project/bundle roots.
+ *
+ * @public
+ */
+interface ResolvedProjectConfig {
+  readonly projectRoot: string;
+  readonly bundleRoot: string;
+  readonly config: OkfitConfig;
+  readonly profile: Option.Option<Profile>;
+  readonly profileName: string;
+  readonly discovered: Option.Option<DiscoveredConfig>;
+}
+/**
+ * Input to {@link resolveProjectConfig}: the same three values every command
+ * handler already has in hand (its own `[path]` argument, its own
+ * `--config` flag, and `process.cwd()`) — nothing this function needs is
+ * read from `process` itself.
+ *
+ * @public
+ */
+interface ResolveProjectConfigInput {
+  readonly pathArg: Option.Option<string>;
+  readonly explicitConfigPath: Option.Option<string>;
+  readonly cwd: string;
+}
+/**
+ * The config-resolution step byte-identical between `validate` and
+ * `context`'s handlers (A2 review finding): discover, pick `sources[0]`,
+ * default `{ extensions: {} }`, resolve the profile name and the K-4
+ * unknown-profile warning, merge `DEFAULTS < profile < file` (D-28), warn on
+ * an `okf_version` mismatch (K-15), then resolve the project and bundle
+ * roots (K-12). Every message string and the merge order are unchanged from
+ * the two commands' former inline copies.
+ *
+ * @public
+ */
+export declare const resolveProjectConfig: (input: ResolveProjectConfigInput) => Effect.Effect<ResolvedProjectConfig, ConfigReadError, OkfitConfigFile | Path.Path>;
+//#endregion
+//#region src/context/run.d.ts
+/** @public */
+interface ContextRunOptions {
+  readonly bundleRoot: string;
+}
+/** @public */
+interface ContextResult {
+  readonly indexPath: string;
+  readonly indexExists: boolean;
+}
+/**
+ * The whole of `context`'s filesystem work: join `index.md` onto the bundle
+ * root and stat it. Loading a bundle and running conformance/lint checks
+ * over it never happen here — that is what makes `context` cheap enough
+ * for a hook to run on every session start and every in-bundle write
+ * (M-15).
+ *
+ * `"index.md"` is a literal here, not read from the profile's layout: the
+ * spec fixes the reserved filename regardless of profile, and a
+ * profile-less merge (`profile = "none"`) has no layout to read from at
+ * all — `context` behaves identically with and without a profile.
+ *
+ * `exists` is `(path) => Effect.Effect<boolean, PlatformError>`, so an
+ * unreadable parent directory would otherwise fail the command; here it is
+ * absorbed to `false`, because "the hook could not stat index.md" and
+ * "index.md is not there" are the same fact from a consumer's point of
+ * view.
+ *
+ * @public
+ */
+export declare const runContext: (options: ContextRunOptions) => Effect.Effect<ContextResult, never, FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/init/scaffold.d.ts
+/** `.config/okfit.toml`, relative to the project root (C-10). @public */
+export declare const CONFIG_RELATIVE_PATH = ".config/okfit.toml";
+/** C-22's directive, plus the blank line Tombi requires. @public */
+export declare const SCHEMA_DIRECTIVE = "#:schema https://raw.githubusercontent.com/spencerbeggs/okfit/main/schemas/config/okfit-1.0.0.json\n\n";
+/** @public */
+interface ScaffoldOptions {
+  /** Absolute. */
+  readonly projectRoot: string;
+  /** Absolute; `<projectRoot>/<bundle.path>`. */
+  readonly bundleRoot: string;
+  /** The resolved profile's `layout` (`PROFILES/Profile.ts:35-38`, P-26). */
+  readonly layout: Layout;
+  /** The name written into the config and the log entry. */
+  readonly profileName: string;
+  /** `basename(projectRoot)` — `project.md`'s `title` (K-26). */
+  readonly projectTitle: string;
+  /** `YYYY-MM-DD`, derived from the CLI's `now` (K-25, K-47). */
+  readonly today: string;
+}
+/** One file `init` will write. Pure data; this module imports no `FileSystem`. @public */
+interface ScaffoldFile {
+  /** Absolute. */
+  readonly path: string;
+  readonly contents: string;
+}
+/**
+ * K-23: the THIN override only — never the merged config. `bundle.path` is
+ * the bundle root relative to the project root; `extensions: {}` satisfies
+ * `OkfitConfig`'s one non-optional field (`CORE/OkfitConfig.ts:164`).
+ * Everything else resolves from `DEFAULTS` and the profile at load time.
+ * `actors.agent` is deliberately absent (K-24, P-17).
+ *
+ * @public
+ */
+export declare const configValue: (options: ScaffoldOptions & {
+  readonly bundlePath: string;
+}) => OkfitConfig;
+/**
+ * Every path `init` will create, absolute, in write order, for the K-28
+ * pre-flight: the three project-level config names, the bundle root's
+ * `index.md`/`log.md`/`project.md`, then one `index.md` per layout directory
+ * in `layout`'s own declared order — never re-sorted here. `Derive.renderIndex`
+ * sorts its own `Subdirectories` section independently (C13), so this
+ * function's order has no bearing on the rendered index text.
+ *
+ * @public
+ */
+export declare const targetPaths: (options: ScaffoldOptions) => ReadonlyArray<string>;
+/**
+ * The three root markdown files and the per-directory indexes (K-25 to
+ * K-27, K-59). `project.md`'s frontmatter is written with
+ * `MarkdownFrontmatter.setToString` — the INSERT path, since the body below
+ * carries no frontmatter block of its own (`MD/index.d.ts:1959`,
+ * `FrontmatterWriteError`'s own doc comment: "a document with no frontmatter
+ * capture is the insert path, not an error"). The root `index.md` is
+ * `Derive.renderIndex` over a `LoadedConcept` this function synthesizes from
+ * the just-rendered `project.md` text, re-parsed with `MarkdownDocument.parse`
+ * (K-59; `renderIndex` reads only `frontmatter.type`/`title`/`description`
+ * and `path`, never `document`, `CORE/Derive.ts:75-101`, so the synthesized
+ * value is faithful). Each per-directory `index.md` is the literal
+ * `# <Directory>` — NOT `Derive.renderIndex`, which returns the empty string
+ * for an empty concept list with no options (contract Judge notes item 2).
+ *
+ * @public
+ */
+export declare const files: (options: ScaffoldOptions) => Effect.Effect<ReadonlyArray<ScaffoldFile>, MarkdownParseError | FrontmatterWriteError>;
+//#endregion
+//#region src/platform.d.ts
+/**
+ * K-9/K-11: `AppDirs.layer(options)` requires `Xdg | FileSystem | Path`, so
+ * `Layer.provide(Xdg.layer)` alone does not close it.
+ * `Layer.provideMerge(NodeServices.layer)` supplies `FileSystem`/`Path` to
+ * both members and keeps every service in the output.
+ * `NodeServices.layer` provides `ChildProcessSpawner | Crypto | FileSystem | Path | Stdio | Terminal`,
+ * a superset of `Command.Environment`.
+ *
+ * K-13: `Xdg.layer` fails with `XdgEnvError` when `HOME` is unset. Callers
+ * are responsible for providing this layer INSIDE whatever region renders
+ * their failures, so that error is rendered rather than escaping to a
+ * fatal stack trace.
+ *
+ * @public
+ */
+export declare const OkfitPlatform: Layer.Layer<AppDirs | Xdg | NodeServices.NodeServices, import("@effected/xdg").XdgEnvError, never>;
+//#endregion
+//#region src/render/context.d.ts
+/** One `types[]` entry (M-15). @public */
+export declare const ContextType: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly description: Schema.NullOr<Schema.String>;
+  readonly guidance: Schema.NullOr<Schema.String>;
+}>;
+/** @public */
+export type ContextType = typeof ContextType.Type;
+/** One `tags[]` entry (M-15). @public */
+export declare const ContextTag: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly description: Schema.NullOr<Schema.String>;
+}>;
+/** @public */
+export type ContextTag = typeof ContextTag.Type;
+/**
+ * M-15's envelope: schema 1, snake_case, orientation data only. Distinct
+ * from `JsonEnvelope` (`render/json.ts`) — `context` never runs conformance
+ * or lint checks, so there is no `diagnostics` array and no `exit_code`
+ * field at all.
+ *
+ * Every field is `Schema.NullOr`, never `Schema.optionalKey`: a consumer
+ * (the two hook scripts) reads a fixed key set and gets JSON `null` for an
+ * absent value, rather than having to distinguish a missing key from a
+ * null one. This is a deliberate difference from `JsonDiagnostic`'s
+ * `range`, which is `optionalKey` and omitted when absent
+ * (`render/json.ts:14,68`).
+ *
+ * `profile_requested` (final-review Important 1) is the profile name the
+ * config asked for after the K-4 default rule — `resolveProjectConfig`'s
+ * own `profileName` — and is `null` only when no config file was found at
+ * all. `profile` keeps its original meaning (the resolved profile's name,
+ * or `null` when the requested name is unknown or `"none"`). The two
+ * differ exactly when a config named an unrecognised profile: `profile`
+ * is `null` but `profile_requested` still names what was asked for, so a
+ * consumer can tell "no profile configured" apart from "an unknown profile
+ * was configured".
+ *
+ * @public
+ */
+export declare const ContextEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly project_root: Schema.String;
+  readonly bundle_root: Schema.String;
+  readonly config_path: Schema.NullOr<Schema.String>;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly profile_requested: Schema.NullOr<Schema.String>;
+  readonly index_path: Schema.String;
+  readonly index_exists: Schema.Boolean;
+  readonly actors: Schema.Struct<{
+    readonly agent: Schema.NullOr<Schema.String>;
+  }>;
+  readonly types: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly guidance: Schema.NullOr<Schema.String>;
+  }>>;
+  readonly tags: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+  }>>;
+}>;
+/** @public */
+export type ContextEnvelope = typeof ContextEnvelope.Type;
+/**
+ * Build the envelope from the merged config. `types`/`tags` sort by `name`
+ * with plain code-unit comparison, never locale-dependent — the same rule
+ * `render/sort.ts`'s K-17 comparator and
+ * `packages/profiles/src/SoftwareProject.ts:119`'s own sort use.
+ *
+ * @public
+ */
+export declare const contextEnvelope: (input: {
+  readonly projectRoot: string;
+  readonly bundleRoot: string;
+  readonly configPath: string | null;
+  readonly profile: string | null;
+  readonly profileRequested: string | null;
+  readonly indexPath: string;
+  readonly indexExists: boolean;
+  readonly config: OkfitConfig;
+}) => ContextEnvelope;
+//#endregion
+//#region src/render/sort.d.ts
+/** Which producer a diagnostic came from; the JSON envelope's `source` (K-21). @public */
+type DiagnosticSource = "core.conformance" | "core.lint" | "profile";
+/**
+ * The one shape both renderers consume. `file` is the bundle-relative posix
+ * path core produced, `""` for a bundle-level finding. `range` is core's own
+ * zero-based `DiagnosticRange` instance, passed through untouched (K-21).
+ * `code` is widened to `string`: core's `DiagnosticCode`
+ * (`CORE/Diagnostic.ts:45-46`) and profiles' `ProfileDiagnosticCode`
+ * (`PROFILES/Profile.ts:47`) are disjoint closed unions and this carries
+ * either.
+ *
+ * @public
+ */
+interface RenderedDiagnostic {
+  readonly source: DiagnosticSource;
+  readonly file: string;
+  readonly range?: DiagnosticRange;
+  readonly code: string;
+  readonly severity: DiagnosticSeverity;
+  readonly message: string;
+}
+/**
+ * Tag core's two arrays and profiles' one, in producer order. Not named
+ * `merge`: `OkfitConfig.merge` already owns that word in this codebase.
+ *
+ * @public
+ */
+export declare const collect: (conformance: ReadonlyArray<Diagnostic>, lint: ReadonlyArray<Diagnostic>, profile: ReadonlyArray<ProfileDiagnostic>) => ReadonlyArray<RenderedDiagnostic>;
+/**
+ * K-17: `file` ascending (so `""` — the bundle-level finding — leads), then
+ * range-less before ranged within a file, then `range.offset` ascending, then
+ * `code`. Plain code-unit comparison, never locale-dependent (the same rule
+ * profiles' own `check` sorts by, `PROFILES/SoftwareProject.ts:119`). Stable:
+ * implemented with `toSorted`, which is specified as stable.
+ *
+ * @public
+ */
+export declare const sort: (diagnostics: ReadonlyArray<RenderedDiagnostic>) => ReadonlyArray<RenderedDiagnostic>;
+//#endregion
+//#region src/render/exit.d.ts
+/** @public */
+interface Tally {
+  readonly conformanceErrors: number;
+  readonly lintErrors: number;
+  readonly lintWarnings: number;
+  readonly lintInfo: number;
+  readonly profileErrors: number;
+}
+/**
+ * One pass over the collected diagnostics. `core.conformance` entries are
+ * always severity `error` (D-33); the counts are still taken from `severity`
+ * so a future non-error conformance code cannot silently change the exit
+ * code.
+ *
+ * @public
+ */
+export declare const tally: (diagnostics: ReadonlyArray<RenderedDiagnostic>) => Tally;
+/**
+ * K-7/K-8's two lowest tiers: `2` when any conformance error is present, else
+ * `1` when any lint OR profile error is present, else `0`. Warnings and info
+ * never move it. `130`, `64` and `3` are set elsewhere — by the runtime's
+ * interrupt branch, by the `ShowHelp` remap in `bin.ts`, and by the typed
+ * errors' own `[Runtime.errorExitCode]` — so this function returns only
+ * `0 | 1 | 2`.
+ *
+ * @public
+ */
+export declare const forDiagnostics: (diagnostics: ReadonlyArray<RenderedDiagnostic>) => 0 | 1 | 2;
+//#endregion
+//#region src/render/json.d.ts
+/** One entry of the `diagnostics` array (K-21). @public */
+export declare const JsonDiagnostic: Schema.Struct<{
+  readonly source: Schema.Literals<readonly ["core.conformance", "core.lint", "profile"]>;
+  readonly file: Schema.String;
+  readonly code: Schema.String;
+  readonly severity: Schema.Literals<readonly ["error", "warning", "info"]>;
+  readonly message: Schema.String;
+  readonly range: Schema.optionalKey<typeof DiagnosticRange>;
+}>;
+/** @public */
+export type JsonDiagnostic = typeof JsonDiagnostic.Type;
+/** @public */
+export declare const JsonSummary: Schema.Struct<{
+  readonly conformance_errors: Schema.Number;
+  readonly lint_errors: Schema.Number;
+  readonly lint_warnings: Schema.Number;
+  readonly lint_info: Schema.Number;
+  readonly profile_errors: Schema.Number;
+  readonly concepts: Schema.Number;
+}>;
+/** @public */
+export type JsonSummary = typeof JsonSummary.Type;
+/**
+ * K-21's success envelope, snake_case. `exit_code` is `0 | 1 | 2` only: an
+ * infrastructure failure never produces this envelope, it produces the
+ * `JsonErrorEnvelope` (K-22).
+ *
+ * @public
+ */
+export declare const JsonEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly okf_version: Schema.String;
+  readonly root: Schema.String;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly exit_code: Schema.Literals<readonly [0, 1, 2]>;
+  readonly summary: Schema.Struct<{
+    readonly conformance_errors: Schema.Number;
+    readonly lint_errors: Schema.Number;
+    readonly lint_warnings: Schema.Number;
+    readonly lint_info: Schema.Number;
+    readonly profile_errors: Schema.Number;
+    readonly concepts: Schema.Number;
+  }>;
+  readonly diagnostics: Schema.$Array<Schema.Struct<{
+    readonly source: Schema.Literals<readonly ["core.conformance", "core.lint", "profile"]>;
+    readonly file: Schema.String;
+    readonly code: Schema.String;
+    readonly severity: Schema.Literals<readonly ["error", "warning", "info"]>;
+    readonly message: Schema.String;
+    readonly range: Schema.optionalKey<typeof DiagnosticRange>;
+  }>>;
+}>;
+/** @public */
+export type JsonEnvelope = typeof JsonEnvelope.Type;
+/** K-22's envelope: the ONLY thing stdout carries under `--format json` on an exit-3 failure. @public */
+export declare const JsonErrorEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly exit_code: Schema.Literal<3>;
+  readonly error: Schema.Struct<{
+    readonly tag: Schema.String;
+    readonly message: Schema.String;
+  }>;
+}>;
+/** @public */
+export type JsonErrorEnvelope = typeof JsonErrorEnvelope.Type;
+/**
+ * Build the success envelope. `diagnostics` is sorted here with the same
+ * `sort` the human renderer uses (K-21's "diagnostics are in the K-17
+ * order"); `range` passes through as core computed it, zero-based.
+ *
+ * The value returned is in `Type` form (its `range`s are `DiagnosticRange`
+ * instances). What stdout carries is `Schema.encodeSync(JsonEnvelope)` of it,
+ * `JSON.stringify`-ed — one document, no trailing text.
+ *
+ * @public
+ */
+export declare const json: (input: {
+  readonly okfitVersion: string;
+  readonly okfVersion: string;
+  readonly root: string;
+  readonly profile: string | null;
+  readonly exitCode: 0 | 1 | 2;
+  readonly concepts: number;
+  readonly diagnostics: ReadonlyArray<RenderedDiagnostic>;
+}) => JsonEnvelope;
+/** K-22. `tag` is the error's `_tag` when it has one, else its constructor name. @public */
+export declare const jsonError: (error: unknown, okfitVersion: string) => JsonErrorEnvelope;
+//#endregion
+//#region src/sync/run.d.ts
+/** The three families `okfit sync` regenerates (contract §5). @public */
+type SyncMode = "generated" | "index" | "log";
+/**
+ * S-14: a closed union, not free text. The human renderer maps each member
+ * to one fixed sentence (`render/sync.ts#humanSync`); the JSON envelope's
+ * `skipped[].reason` is this exact union.
+ *
+ * @public
+ */
+export declare const SkipReason: Schema.Literals<readonly ["untracked", "dirty", "unborn", "generated-missing", "generated-unsupported", "log-unparseable"]>;
+/** @public */
+export type SkipReason = typeof SkipReason.Type;
+/** @public */
+interface SyncOptions {
+  /** Absolute bundle root, from `resolveProjectConfig`. */
+  readonly bundleRoot: string;
+  /** Already merged `DEFAULTS < profile < file` by the caller (D-28); unused today (`sync` never calls `profile.check`) but carried for parity with `RunOptions`. */
+  readonly config: OkfitConfig;
+  /** Members to actually RUN. Absent members still appear in {@link SyncResult}, `selected: false`. */
+  readonly modes: ReadonlySet<SyncMode>;
+  readonly dryRun: boolean;
+}
+/** @public */
+interface SyncModeResult {
+  readonly selected: boolean;
+  /** Bundle-relative. `generated`'s ids have no `.md`; `index`/`log`'s paths do (design §2). */
+  readonly written: ReadonlyArray<string>;
+  readonly unchanged: ReadonlyArray<string>;
+  readonly skipped: ReadonlyArray<{
+    readonly id: string;
+    readonly reason: SkipReason;
+  }>;
+}
+/** @public */
+interface SyncResult {
+  readonly bundleRoot: string;
+  readonly dryRun: boolean;
+  readonly generated: SyncModeResult;
+  readonly index: SyncModeResult;
+  readonly log: SyncModeResult;
+}
+/**
+ * Contract §5's six-step algorithm: one `Bundle.load`, one
+ * `Derivation.generatedAt` per concept shared by the generated and log
+ * modes (skipped entirely when neither is selected), then the three modes
+ * in a FIXED order — generated, index, log — regardless of `--only`'s own
+ * occurrence order, so a generated write never invalidates an index or log
+ * rendered in the same run (design §2).
+ *
+ * @public
+ */
+export declare const runSync: (options: SyncOptions) => Effect.Effect<SyncResult, BundleLoadError | GeneratedAtError, Git | GitHistory | FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/render/sync.d.ts
+/** @public */
+export declare const SyncModeEnvelope: Schema.Struct<{
+  readonly selected: Schema.Boolean;
+  readonly written: Schema.$Array<Schema.String>;
+  readonly unchanged: Schema.$Array<Schema.String>;
+  readonly skipped: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn", "generated-missing", "generated-unsupported", "log-unparseable"]>;
+  }>>;
+}>;
+/** @public */
+export type SyncModeEnvelope = typeof SyncModeEnvelope.Type;
+/**
+ * Contract §14 note 5: `schema: 1` is INFERRED, not in the design's own
+ * §2 JSON example — every other envelope in this codebase
+ * (`JsonEnvelope`, `VerifyEnvelope`, `ContextEnvelope`) opens with it, so
+ * this one does too. `exit_code` is the literal `0`: `sync` has no
+ * content tier (unlike `validate`'s `0 | 1 | 2`) and this envelope only
+ * exists on the success path — a failure produces `JsonErrorEnvelope`
+ * (K-22) instead, unchanged.
+ *
+ * @public
+ */
+export declare const SyncEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly root: Schema.String;
+  readonly dry_run: Schema.Boolean;
+  readonly exit_code: Schema.Literal<0>;
+  readonly generated: Schema.Struct<{
+    readonly selected: Schema.Boolean;
+    readonly written: Schema.$Array<Schema.String>;
+    readonly unchanged: Schema.$Array<Schema.String>;
+    readonly skipped: Schema.$Array<Schema.Struct<{
+      readonly id: Schema.String;
+      readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn", "generated-missing", "generated-unsupported", "log-unparseable"]>;
+    }>>;
+  }>;
+  readonly index: Schema.Struct<{
+    readonly selected: Schema.Boolean;
+    readonly written: Schema.$Array<Schema.String>;
+    readonly unchanged: Schema.$Array<Schema.String>;
+    readonly skipped: Schema.$Array<Schema.Struct<{
+      readonly id: Schema.String;
+      readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn", "generated-missing", "generated-unsupported", "log-unparseable"]>;
+    }>>;
+  }>;
+  readonly log: Schema.Struct<{
+    readonly selected: Schema.Boolean;
+    readonly written: Schema.$Array<Schema.String>;
+    readonly unchanged: Schema.$Array<Schema.String>;
+    readonly skipped: Schema.$Array<Schema.Struct<{
+      readonly id: Schema.String;
+      readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn", "generated-missing", "generated-unsupported", "log-unparseable"]>;
+    }>>;
+  }>;
+}>;
+/** @public */
+export type SyncEnvelope = typeof SyncEnvelope.Type;
+/**
+ * `root` alone goes through `displayRoot` at the call site
+ * (`commands/sync.ts`) — `generated`/`index`/`log`'s own lists are
+ * already bundle-relative and need no cwd-relativisation (contract §9.1).
+ *
+ * @public
+ */
+export declare const syncEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly root: string;
+  readonly dryRun: boolean;
+  readonly result: SyncResult;
+}) => SyncEnvelope;
+//#endregion
+//#region src/render/verify.d.ts
+/**
+ * V-11's success envelope, schema 1, snake_case — the same convention as
+ * `render/json.ts`'s `JsonEnvelope`. Identical in shape for a dry run,
+ * which sets `dry_run: true` and still exits 0. There is no content tier,
+ * so `exit_code` is the literal `0`; a failure produces K-22's
+ * `JsonErrorEnvelope` instead, unchanged.
+ *
+ * @public
+ */
+export declare const VerifyEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly id: Schema.String;
+  readonly path: Schema.String;
+  readonly verified: Schema.Struct<{
+    readonly by: Schema.String;
+    readonly at: Schema.String;
+  }>;
+  readonly dry_run: Schema.Boolean;
+  readonly exit_code: Schema.Literal<0>;
+}>;
+/** @public */
+export type VerifyEnvelope = typeof VerifyEnvelope.Type;
+/**
+ * `path` is already the display form — `displayRoot(cwd, bundle.root, path)`
+ * joined to the bundle-relative `concept.path` — because `LoadedConcept.path`
+ * alone would print `decisions/cli-exit-codes.md`, not
+ * `okf/decisions/cli-exit-codes.md` (contract §12 note 5).
+ *
+ * @public
+ */
+export declare const verifyEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly id: string;
+  readonly path: string;
+  readonly by: string;
+  readonly at: string;
+  readonly dryRun: boolean;
+}) => VerifyEnvelope;
+//#endregion
+//#region src/validate/run.d.ts
+declare const Now_base: Context.ServiceClass<Now, "@okfit/engine/Now", DateTime.Utc>;
+/**
+ * K-47's ambient clock. `bin.ts` resolves `OKFIT_NOW` (or the wall clock)
+ * exactly once and provides it with `Effect.provideService(Now, value)`
+ * around the whole command tree; `commands/validate.ts` and
+ * `commands/init.ts` each read it with `const now = yield* Now;` before
+ * building {@link RunOptions} or a scaffold's `today`. Not re-exported from
+ * `index.ts`: like `internal/exit.ts` and `internal/tty.ts`, it means
+ * nothing outside a spawned process (K-49). `Context.Tag` does not exist on
+ * the Effect v4 line; the v4 shape is
+ * `Context.Service<Self, Shape>()(id)`, the same form core and profiles use
+ * for their own services (`PROFILES/GitHistory.ts:140`) — source wins over
+ * the contract's literal snippet here (K-62).
+ *
+ * @internal
+ */
+export declare class Now extends Now_base {}
+/** @public */
+interface RunOptions {
+  /** Absolute bundle root; `Bundle.load` never reads cwd (D-8). */
+  readonly root: string;
+  /** Already merged `DEFAULTS < profile < file` by the caller (D-28). */
+  readonly config: OkfitConfig;
+  /** The resolved profile, when `Profiles.get` found one. */
+  readonly profile: Option.Option<Profile>;
+  /** `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.
+   */
+  readonly skipProvenance?: boolean;
+}
+/** @public */
+interface RunResult {
+  readonly bundle: LoadedBundle;
+  readonly report: ValidationReport;
+  /** `[]` when `profile` is `None`. */
+  readonly profileDiagnostics: ReadonlyArray<ProfileDiagnostic>;
+}
+/**
+ * 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
+ * (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
+ * the same `report.lint` array every other core lint diagnostic already
+ * does.
+ *
+ * K-52 holds structurally: `Bundle.load`'s failure short-circuits the
+ * generator, so `profile.check` never runs on a bundle that did not load.
+ *
+ * This is a BREAKING signature change: `@okfit/mcp`'s `validateBundle.ts`
+ * calls this function directly and must be updated to match (Task C1);
+ * `commands/validate.ts` is the other caller.
+ *
+ * @public
+ */
+export declare const run: (options: RunOptions) => Effect.Effect<RunResult, BundleLoadError | GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Git | GitHistory>;
+//#endregion
+//#region src/verify/run.d.ts
+/** @internal */
+interface VerifyOptions {
+  readonly id: string;
+  /** Absolute bundle root, from `resolveProjectConfig`. */
+  readonly bundleRoot: string;
+  /** Absolute project root — V-7 spells `generatedBy`'s cwd as exactly this. */
+  readonly projectRoot: string;
+  /** Already merged `DEFAULTS < profile < file` by the caller (D-28). */
+  readonly config: OkfitConfig;
+  /** `--at` when given, else the `Now` service (K-47/K-49). */
+  readonly at: DateTime.Utc;
+  readonly dryRun: boolean;
+}
+/** @internal */
+interface VerifyResult {
+  readonly id: string;
+  /** Absolute bundle root, echoed back for `displayRoot`. */
+  readonly bundleRoot: string;
+  /** Posix bundle-relative path with `.md`, straight off `LoadedConcept.path`. */
+  readonly conceptPath: string;
+  /** The branded actor string, e.g. `human:spencer`. */
+  readonly by: string;
+  /** The `Timestamp`-encoded ISO string actually recorded. */
+  readonly at: string;
+  /** Every PRIOR entry by this same actor, in list order, encoded (V-2). */
+  readonly priorAt: ReadonlyArray<string>;
+  readonly dryRun: boolean;
+  /** The exact bytes `splice`'s edit would insert, written or not. */
+  readonly fragment: string;
+}
+/**
+ * Contract §2.3 steps 6–15. Loads the bundle, resolves the id, resolves the
+ * human actor from git, splices exactly one entry into the concept's
+ * frontmatter and writes it back atomically.
+ *
+ * Nothing here reads `status`, `stale_after`, or a type's
+ * `require_verified`: `verify` is mechanical, not config-aware (V-4, V-5).
+ *
+ * @internal
+ */
+export declare const runVerify: (options: VerifyOptions) => Effect.Effect<{
+  id: ConceptId;
+  bundleRoot: string;
+  conceptPath: string;
+  by: import("@okfit/core").Actor;
+  at: string;
+  priorAt: string[];
+  dryRun: boolean;
+  fragment: string;
+}, import("effect/PlatformError").PlatformError | VerifyConceptNotFoundError | VerifyUnsupportedFrontmatterError | import("@effected/yaml").YamlParseError | import("@okfit/core").BundleLoadError | import("@okfit/profiles").GeneratedByError, FileSystem.FileSystem | import("@effected/git").Git | Path.Path>;
+//#endregion
+export type { ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyOptions, VerifyResult };
+//# sourceMappingURL=index.d.ts.map