@smthrs/plan 0.0.0-stage → 1.0.0-rc.12

package/src/FileSet.ts

@@ -0,0 +1,493 @@
+/**
+ * Static filesystem declaration vocabulary shared by planning and execution.
+ *
+ * Declared paths use `/` as their canonical separator and normalize Unicode
+ * to NFC. Workspace-relative paths reject C0 controls (U+0000 through U+001F)
+ * and DEL (U+007F), which name nothing a supported filesystem can open. C1
+ * controls (U+0080 through U+009F) remain accepted because those bytes are
+ * legal in a POSIX file name.
+ *
+ * @since 0.1.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * How strictly a declared file set is enforced at the boundary.
+ *
+ * `hard` rejects undeclared access. `expected` records access for validation
+ * after execution without requiring the sandbox to reject it immediately.
+ *
+ * This is the ONE spelling of the pair. `Plan.NodeEffects.boundaryMode` is this
+ * schema and so is `@smthrs/flow`'s `Action.BoundaryMode`; the literal used to
+ * be written out in all three places.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const BoundaryMode = Schema.Literals(["hard", "expected"])
+
+/**
+ * The value form of {@link BoundaryMode}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type BoundaryMode = typeof BoundaryMode.Type
+
+/**
+ * The canonical spelling of a declared path or pattern: every separator is
+ * `/`, and Unicode is normalized to NFC.
+ *
+ * {@link workspaceRelative} accepts a backslash as a separator, so
+ * `dist\same.js` and `dist/same.js` are two spellings of ONE workspace path.
+ * Every exact-path comparison in this module goes through this form, because
+ * comparing the raw spellings would let the separator alias defeat overlap
+ * detection exactly as `.` segments and empty segments would.
+ *
+ * @category accessors
+ * @since 0.1.0
+ */
+export const canonical = (path: string): string => path.replaceAll("\\", "/").normalize("NFC")
+
+/**
+ * The {@link canonical} spelling with letter case folded away.
+ *
+ * A case-insensitive filesystem (default macOS APFS, Windows NTFS) opens
+ * `src/A.ts` and `src/a.ts` as one file, so static overlap compares this form:
+ * two declarations that differ only in case must serialize. Folding goes
+ * through upper case because that mapping is context-free, so it folds each
+ * character alone and commutes with splitting a path into segments.
+ *
+ * @category accessors
+ * @since 1.0.0-rc.0
+ */
+export const folded = (path: string): string => canonical(path).toUpperCase().normalize("NFC")
+
+/**
+ * A non-empty workspace-relative path or pattern.
+ *
+ * Decoding fails with a `SchemaError` when {@link workspaceRelative} refuses
+ * the string. A bare `Pattern` in a declaration names one literal path; only a
+ * {@link Glob} gives `*` and `**` wildcard meaning.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Pattern = Schema.NonEmptyString.check(
+  Schema.makeFilter(
+    (pattern) => workspaceRelative(pattern) || "file patterns must be workspace-relative and cannot traverse upward",
+    { title: "workspaceRelativePattern" }
+  )
+)
+
+/**
+ * Whether a declared path or pattern stays inside the workspace and names it
+ * one way only. Refuses absolute paths (POSIX and drive-letter), upward
+ * traversal, and the aliasing forms — `.` segments, empty segments — that
+ * would let two spellings of one file defeat exact-string overlap detection.
+ *
+ * C0 controls and DEL are refused as well.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export const workspaceRelative = (pattern: string): boolean => {
+  for (let index = 0; index < pattern.length; index++) {
+    const code = pattern.charCodeAt(index)
+    if (code <= 0x1f || code === 0x7f) return false
+  }
+  if (pattern.startsWith("/")) return false
+  const segments = canonical(pattern).split("/")
+  // `C:foo` is drive-relative on Windows, so any drive-letter prefix escapes.
+  if (/^[A-Za-z]:/.test(segments[0]!) || segments[0]!.endsWith(":")) return false
+  return segments.every((segment) => segment !== ".." && segment !== "." && segment !== "")
+}
+
+/**
+ * A Bazel-style file glob: the paths matching any `include` pattern and no
+ * `exclude` pattern.
+ *
+ * In a pattern, `*` matches within one path segment and a `**` segment
+ * matches zero or more whole segments. A trailing `**` needs its separator,
+ * so `src/**` does not match `src` itself.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Glob = Schema.TaggedStruct("Glob", {
+  include: Schema.NonEmptyArray(Pattern),
+  exclude: Schema.optional(Schema.Array(Pattern))
+})
+
+/**
+ * The value form of {@link Glob}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Glob = typeof Glob.Type
+
+/**
+ * A directory output captured and replayed as one tree artifact.
+ *
+ * It covers `path` and every path beneath it, compared in {@link folded}
+ * form.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const TreeArtifact = Schema.TaggedStruct("TreeArtifact", {
+  path: Pattern
+})
+
+/**
+ * The value form of {@link TreeArtifact}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type TreeArtifact = typeof TreeArtifact.Type
+
+/**
+ * One leaf declaration: a literal path, a {@link Glob}, or a
+ * {@link TreeArtifact}. Write sets and filegroups hold entries.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Entry = Schema.Union([Pattern, Glob, TreeArtifact])
+
+/**
+ * The value form of {@link Entry}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Entry = typeof Entry.Type
+
+/**
+ * One leaf declaration valid in a read set: a literal path or a {@link Glob}.
+ * A read set cannot name a {@link TreeArtifact}, which is an output form.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ReadEntry = Schema.Union([Pattern, Glob])
+
+/**
+ * The value form of {@link ReadEntry}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ReadEntry = typeof ReadEntry.Type
+
+/**
+ * A named, reusable list of {@link Entry} declarations.
+ *
+ * {@link expand} replaces a filegroup with its entries in place before any
+ * overlap check or measurement, so the name never reaches the boundary.
+ * Filegroups do not nest.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Filegroup = Schema.TaggedStruct("Filegroup", {
+  name: Schema.NonEmptyString,
+  entries: Schema.Array(Entry)
+})
+
+/**
+ * The value form of {@link Filegroup}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Filegroup = typeof Filegroup.Type
+
+/**
+ * A {@link Filegroup} restricted to {@link ReadEntry} declarations, for use
+ * in a read set. It shares the `"Filegroup"` tag.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ReadFilegroup = Schema.TaggedStruct("Filegroup", {
+  name: Schema.NonEmptyString,
+  entries: Schema.Array(ReadEntry)
+})
+
+/**
+ * The value form of {@link ReadFilegroup}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ReadFilegroup = typeof ReadFilegroup.Type
+
+/**
+ * Any declaration accepted in a write set: an {@link Entry} or a
+ * {@link Filegroup}.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Declaration = Schema.Union([Entry, Filegroup])
+
+/**
+ * The value form of {@link Declaration}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Declaration = typeof Declaration.Type
+
+/**
+ * Any declaration accepted in a read set: a {@link ReadEntry} or a
+ * {@link ReadFilegroup}.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ReadDeclaration = Schema.Union([ReadEntry, ReadFilegroup])
+
+/**
+ * The value form of {@link ReadDeclaration}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ReadDeclaration = typeof ReadDeclaration.Type
+
+/**
+ * Creates a {@link Filegroup}. It does not validate `name` or `entries`;
+ * decode through {@link Filegroup} when the input is untrusted.
+ *
+ * @param name - The filegroup name.
+ * @param entries - The entries the filegroup expands to, in order.
+ * @returns The filegroup value.
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeFilegroup = (name: string, entries: ReadonlyArray<Entry>): Filegroup => ({
+  _tag: "Filegroup",
+  name,
+  entries
+})
+
+/**
+ * Replaces each {@link Filegroup} with its entries, in place, and keeps every
+ * other declaration as it is. Order is preserved and duplicates are kept.
+ *
+ * @param declarations - Write-set declarations, possibly holding filegroups.
+ * @returns The flat list of entries.
+ * @category accessors
+ * @since 0.1.0
+ */
+export const expand = (declarations: ReadonlyArray<Declaration>): ReadonlyArray<Entry> =>
+  declarations.flatMap((declaration) =>
+    typeof declaration !== "string" && declaration._tag === "Filegroup" ? declaration.entries : [declaration]
+  )
+
+/**
+ * {@link expand} for read sets: replaces each {@link ReadFilegroup} with its
+ * entries, in place, preserving order and duplicates.
+ *
+ * @param declarations - Read-set declarations, possibly holding filegroups.
+ * @returns The flat list of read entries.
+ * @category accessors
+ * @since 0.1.0
+ */
+export const expandReads = (declarations: ReadonlyArray<ReadDeclaration>): ReadonlyArray<ReadEntry> =>
+  declarations.flatMap((declaration) =>
+    typeof declaration !== "string" && declaration._tag === "Filegroup" ? declaration.entries : [declaration]
+  )
+
+/**
+ * Whether a value carries the `"Glob"` tag. It checks only the tag, not the
+ * patterns.
+ *
+ * @param value - Any value.
+ * @returns `true` for an object whose `_tag` is `"Glob"`.
+ * @category guards
+ * @since 0.1.0
+ */
+export const isGlob = (value: unknown): value is Glob =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "Glob"
+
+/**
+ * Whether a value carries the `"TreeArtifact"` tag. It checks only the tag,
+ * not the path.
+ *
+ * @param value - Any value.
+ * @returns `true` for an object whose `_tag` is `"TreeArtifact"`.
+ * @category guards
+ * @since 0.1.0
+ */
+export const isTreeArtifact = (value: unknown): value is TreeArtifact =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "TreeArtifact"
+
+/** KMP searches a literal without rescanning a long near-matching prefix. */
+const literalSearch = (literal: string) => {
+  const fallback = new Uint32Array(literal.length)
+  let matched = 0
+  for (let index = 1; index < literal.length; index++) {
+    while (matched > 0 && literal[index] !== literal[matched]) matched = fallback[matched - 1]!
+    if (literal[index] === literal[matched]) matched++
+    fallback[index] = matched
+  }
+  return (path: string, start: number, end: number): number => {
+    let matched = 0
+    for (let index = start; index < end; index++) {
+      while (matched > 0 && path[index] !== literal[matched]) matched = fallback[matched - 1]!
+      if (path[index] === literal[matched]) matched++
+      if (matched === literal.length) return index + 1
+    }
+    return -1
+  }
+}
+
+/** Anchored ends and disjoint literal searches make each segment match linear. */
+const segmentMatcher = (segment: string): (path: string) => boolean => {
+  const chunks = segment.split(/\*+/)
+  const prefix = chunks.shift()!
+  if (chunks.length === 0) return (path) => path === prefix
+  const suffix = chunks.pop()!
+  const searches = chunks.map(literalSearch)
+  return (path) => {
+    const end = path.length - suffix.length
+    if (prefix.length > end || !path.startsWith(prefix) || !path.endsWith(suffix)) return false
+    let position = prefix.length
+    for (const search of searches) {
+      position = search(path, position, end)
+      if (position === -1) return false
+    }
+    return true
+  }
+}
+
+const patternMatchers = new Map<string, (path: string) => boolean>()
+
+/** Compile once per canonical spelling; recursive segments use no backtracking. */
+const patternMatcher = (pattern: string): (path: string) => boolean => {
+  const key = canonical(pattern)
+  const cached = patternMatchers.get(key)
+  if (cached !== undefined) return cached
+  const segments = key.split("/").map((segment) => segment === "**" ? undefined : segmentMatcher(segment))
+  const matcher = (path: string): boolean => {
+    const parts = path.split("/")
+    // Suffix membership: next[j] says the remaining pattern matches parts[j..].
+    // Each pattern/path segment pair is visited once, even with repeated **.
+    let next = new Uint8Array(parts.length + 1)
+    next[parts.length] = 1
+    for (let index = segments.length - 1; index >= 0; index--) {
+      const segment = segments[index]
+      const current = new Uint8Array(parts.length + 1)
+      for (let part = parts.length - 1; part >= 0; part--) {
+        current[part] = segment === undefined
+          // A trailing ** accepts every remaining code unit. It still needs
+          // the separator preceding it: src/** does not match bare src.
+          ? Number(
+            index === segments.length - 1 || next[part] === 1 ||
+              (parts[part] !== "" && current[part + 1] === 1)
+          )
+          : Number(next[part + 1] === 1 && segment(parts[part]!))
+      }
+      next = current
+    }
+    return next[0] === 1
+  }
+  patternMatchers.set(key, matcher)
+  return matcher
+}
+
+/**
+ * Whether `path` matches `pattern` under {@link Glob} wildcard rules.
+ *
+ * The pattern is read in its {@link canonical} spelling; the path is matched
+ * as given, case-sensitively, with `/` as its only separator.
+ *
+ * @param pattern - A Bazel-style pattern such as `src/*.ts` or `docs/**`.
+ * @param path - A workspace-relative path.
+ * @returns `true` when the path matches.
+ * @category predicates
+ * @since 0.1.0
+ */
+export const matchesPattern = (pattern: string, path: string): boolean => patternMatcher(pattern)(path)
+
+/**
+ * Whether `path` matches some `include` pattern of `glob` and no `exclude`
+ * pattern, each tested with {@link matchesPattern}. Case-sensitive.
+ *
+ * @param glob - The glob to test.
+ * @param path - A workspace-relative path.
+ * @returns `true` when the glob selects the path.
+ * @category predicates
+ * @since 0.1.0
+ */
+export const matchesGlob = (glob: Glob, path: string): boolean =>
+  glob.include.some((pattern) => matchesPattern(pattern, path)) &&
+  !(glob.exclude ?? []).some((pattern) => matchesPattern(pattern, path))
+
+const beneath = (tree: string, path: string): boolean => {
+  const root = folded(tree)
+  const inside = folded(path)
+  return inside === root || inside.startsWith(`${root}/`)
+}
+
+/**
+ * Whether a canonical path is inside a declaration, case-sensitively.
+ * Unlike {@link overlaps}, this predicate establishes replay authority.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.0
+ */
+export const contains = (entry: Entry, path: string): boolean => {
+  const inside = canonical(path)
+  if (typeof entry === "string") return canonical(entry) === inside
+  if (isGlob(entry)) return matchesGlob(entry, inside)
+  const root = canonical(entry.path)
+  return inside === root || inside.startsWith(`${root}/`)
+}
+
+/** Includes fold conservatively; exclusions cannot rule out all case aliases. */
+const mayMatchGlob = (glob: Glob, path: string): boolean =>
+  glob.include.some((pattern) => matchesPattern(folded(pattern), folded(path)))
+
+/**
+ * Conservative static overlap. `true` may over-serialize; `false` proves that
+ * no path can belong to both declarations.
+ *
+ * A plain string is a literal path, even when it contains `*` or `**`, as it
+ * is at execution (sandbox admission, capture, removal, and replay); wildcard
+ * matching belongs to a Glob.
+ *
+ * Exact paths and tree roots compare in their
+ * {@link folded} form, so separator aliases, canonically equivalent Unicode
+ * spellings, and spellings that differ only in letter case overlap. A Glob
+ * against an exact path folds its includes and ignores exclusions: an excluded
+ * spelling may alias an included spelling on another filesystem. {@link matchesGlob} itself stays case-sensitive and tests the path bytes it
+ * is handed; its property suite pins a backslash inside a path segment as
+ * literal text, so canonicalizing a measured path before matching is its
+ * caller's decision, not this module's.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export const overlaps = (left: Entry, right: Entry): boolean => {
+  if (typeof left === "string" && typeof right === "string") return folded(left) === folded(right)
+  if (typeof left === "string" && isGlob(right)) return mayMatchGlob(right, left)
+  if (isGlob(left) && typeof right === "string") return mayMatchGlob(left, right)
+  if (isGlob(left) && isGlob(right)) return true
+  if (isTreeArtifact(left) && typeof right === "string") return beneath(left.path, right)
+  if (typeof left === "string" && isTreeArtifact(right)) return beneath(right.path, left)
+  if (isTreeArtifact(left) && isTreeArtifact(right)) {
+    return beneath(left.path, right.path) || beneath(right.path, left.path)
+  }
+  if (isTreeArtifact(left) && isGlob(right)) return true
+  /* v8 ignore else -- the closed Entry union leaves only Glob/TreeArtifact here */
+  if (isGlob(left) && isTreeArtifact(right)) return overlaps(right, left)
+  /* v8 ignore next -- Entry's closed union makes every pair return above */
+  return true
+}

package/src/GraphBuildError.ts

@@ -0,0 +1,156 @@
+/**
+ * The refusals a plan-time build raises instead of producing a wrong plan.
+ *
+ * Every one of these fails LOUDLY at build time: a planned value that was computed on must not
+ * bake `NaN` into a plan, an arm that returned something other than a node must
+ * not silently vanish from the topology, and a recursive `.call()` must direct
+ * the author to `.to()` or `.child()` rather than expanding forever. Each
+ * failure therefore names the site (`node` plus the recorded property `path`)
+ * and states the fix in `message`, because the author reading it is mid-body
+ * and needs the correction, not a classification.
+ *
+ * The codes are a closed schema literal so a caller can switch on them, and so
+ * a new refusal is a deliberate addition rather than a new free-form string.
+ *
+ * @since 0.1.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * The stable code of a build refusal.
+ *
+ * `planned_value_computed` is a body computing on a step result;
+ * `invalid_all_member` is a non-node handed to {@link module:Node.all};
+ * `invalid_join` is a race, any, or quorum with a non-node member, no members,
+ * or a quorum count its members cannot reach;
+ * `invalid_continuation` is a branch arm or continuation that did not return a
+ * node; `recursion_requires_boundary` is a flow calling itself inline, which
+ * has to become a trampoline handoff or an explicit child boundary;
+ * `placement_requires_boundary` is an inline call whose callee declares a
+ * placement the enclosing flow cannot satisfy, which has to become that same
+ * explicit child boundary; `cyclic_payload` is a payload that contains itself,
+ * which no plan could serialize or hash; `payload_too_deep` is a payload
+ * nested past the build bound, which has to be flattened into shallower data;
+ * `graph_too_deep` is authored topology nested past the build bound, which
+ * has to be split with `.child()` boundaries or trampoline handoffs;
+ * `duplicate_node` is two structural graph addresses resolving to one durable
+ * node id;
+ * `invalid_priority` is a scheduling priority that is not a safe integer,
+ * which no ordering could compare; `invalid_payload` is a payload member that
+ * cannot be captured as inert JSON without executing author code or losing
+ * identity; `unstable_callback` is a function with process-local identity in a
+ * graph that requires stable callbacks. Declare its complete inert captures
+ * with `Node.capture`, including semantic implementation versions. The two
+ * depth refusals exist because graph building walks with an explicit stack
+ * and refuses at a bound, rather than recursing until the native stack
+ * overflows without a typed error.
+ *
+ * The four effect-authority refusals are raised when a declaration claims more
+ * than the declaration enclosing it granted:
+ * `effect_outside_envelope` is a read or write path the envelope does not
+ * cover, and it names those paths in `path`; `effect_mode_widening` is an
+ * `expected` declaration inside a `hermetic` envelope; `effect_tier_widening`
+ * is a tier less reversible than the envelope's; and
+ * `capability_outside_grant` is a called flow or action requiring a capability
+ * the caller does not hold, which names the dropped capabilities in `path`. The
+ * first three are fatal by {@link isFatalDiagnostic}; the fourth is advisory,
+ * because dropping a capability narrows authority rather than widening it.
+ *
+ * The last six are raised by `@smthrs/core`'s graph builder, which uses this
+ * one error rather than a second class of its own. `write_conflict` is two work
+ * nodes overlapping under `onConflict: "fail"`, and `node` names the first of
+ * the pair while `Graph.conflicts` carries both; `missing_key_material` is a
+ * node that reached key compilation without any; `dependency_cycle` is a
+ * dependency set that cannot be ordered, and `node` names a node in the cycle;
+ * `plan_too_large` is a node, edge, conflict, or effect-path limit crossed, and
+ * `node` names the node whose admission crossed it; `payload_too_large` is a
+ * plan value with more members than the bound, and `path` names the offending
+ * value path; `invalid_node` is a malformed node AST. All six are fatal.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const GraphBuildErrorCode = Schema.Literals([
+  "planned_value_computed",
+  "invalid_all_member",
+  "invalid_join",
+  "invalid_continuation",
+  "recursion_requires_boundary",
+  "placement_requires_boundary",
+  "cyclic_payload",
+  "payload_too_deep",
+  "graph_too_deep",
+  "duplicate_node",
+  "invalid_priority",
+  "invalid_payload",
+  "unstable_callback",
+  "effect_outside_envelope",
+  "effect_mode_widening",
+  "effect_tier_widening",
+  "capability_outside_grant",
+  "write_conflict",
+  "missing_key_material",
+  "dependency_cycle",
+  "plan_too_large",
+  "payload_too_large",
+  "invalid_node"
+])
+
+/**
+ * The value form of {@link GraphBuildErrorCode}.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type GraphBuildErrorCode = typeof GraphBuildErrorCode.Type
+
+/**
+ * A build the planner refuses, naming the site and the fix.
+ *
+ * `node` is the node reference the failure belongs to — a planned value's
+ * origin node, an `all` member name, a branch arm, or the node whose admission
+ * crossed a bound. `path` is the property path recorded on a planned value
+ * before it was misused, the effect paths an over-claiming declaration named,
+ * the capabilities a call lost, or the value path of an oversized payload; it
+ * is empty for every other code.
+ *
+ * This is the ONE build refusal. `@smthrs/core`'s graph builder raised a second
+ * `GraphBuildError` of its own, with `paths`, `nodeId` and `nodes` in place of
+ * these fields, and the two code sets diverged instead of merging. A conflict's
+ * second node is read from `Graph.conflicts`, which carries the pair.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class GraphBuildError extends Schema.TaggedError<GraphBuildError>()("@smthrs/plan/GraphBuildError", {
+  code: GraphBuildErrorCode,
+  node: Schema.String,
+  path: Schema.Array(Schema.String),
+  message: Schema.String
+}) {}
+
+/**
+ * The one advisory code. Everything else a build records blocks the drafts.
+ *
+ * A capability the caller does not grant is DROPPED, not granted: the callee
+ * runs with less authority than it asked for, which is the safe direction. The
+ * author still needs to know, because a flow that silently loses a capability
+ * fails later at the action that needed it, so the build records the refusal
+ * and lets the graph compile.
+ */
+const advisoryCodes: ReadonlySet<GraphBuildErrorCode> = new Set<GraphBuildErrorCode>(["capability_outside_grant"])
+
+/**
+ * Whether a recorded refusal blocks the drafts a plan is compiled from.
+ *
+ * A fatal refusal means the graph describes something no plan could execute as
+ * written, so the drafts are withheld. An advisory one reports a narrowing the
+ * author should see while the graph still compiles.
+ *
+ * @param diagnostic - A recorded refusal.
+ * @returns `false` only for an advisory code (`capability_outside_grant`).
+ * @since 0.1.0
+ * @category predicates
+ */
+export const isFatalDiagnostic = (diagnostic: GraphBuildError): boolean => !advisoryCodes.has(diagnostic.code)