@superbee/core 0.1.0

package/dist/kinds.d.ts

@@ -0,0 +1,241 @@
+import type { ValidationWarning } from "./validation.js";
+import type { ConceptId, Frontmatter, OkfDocument } from "./types.js";
+/** The bundle-relative prefix a kind convention doc MUST live under to be discovered. */
+export declare const CONVENTIONS_PREFIX = "conventions/";
+/** The OKF `type` value a kind convention doc itself carries. */
+export declare const CONVENTION_TYPE = "Convention";
+/** A kind's declared required/optional fields and any enum-restricted field values. */
+export interface KindFields {
+    /** Field names that MUST be present and non-empty on an instance. */
+    required: string[];
+    /** Field names that MAY be present on an instance. */
+    optional: string[];
+    /** `fieldName -> allowed values` for fields restricted to an enumerated set. */
+    values: Record<string, string[]>;
+    /** Human guidance for allowed enum values: `fieldName -> value -> description`. */
+    valueDescriptions?: Record<string, Record<string, string>>;
+    /**
+     * `fieldName -> terminal values` (a subset of that field's `values` enum, when declared) — the
+     * states past which an instance is "done" (task board `tasks/status-terminal-declaration.md`).
+     * Consumed via {@link isTerminal}, the ONE derivation every consumer (list's `--open`, the
+     * `status` sweep's exclusion + sort) calls. Empty map when the kind declares no terminal set.
+     */
+    terminal: Record<string, string[]>;
+    /** Human guidance for declared fields: `fieldName -> description`. */
+    descriptions: Record<string, string>;
+}
+/**
+ * A kind's DECLARED claim vocabulary (`claim:` on the convention doc): which field records who
+ * owns an instance, and which field records its claim state. Declared by the BUNDLE so no
+ * consumer has to spell a workflow word ("assignee", "in_progress") into product code.
+ *
+ * The names here are as authored — LOGICAL. Resolve them onto the edition's real frontmatter keys
+ * with {@link claimCoordinates}; never read frontmatter by the declared name directly.
+ *
+ * Only the two coordinates are represented: the first consumer (sync's ownership report) needs
+ * exactly them. The block's value vocabulary (`claimed`/`unclaimed`/`released`) is deliberately
+ * not parsed yet, and an unrecognized key inside `claim:` is IGNORED rather than warned about —
+ * warning on it would be wrong the moment the rest of the block lands.
+ */
+export interface KindClaimPolicy {
+    /** Declared field recording who owns an instance (`claim.owner_field`). */
+    ownerField?: string;
+    /** Declared field recording an instance's claim state (`claim.state_field`). */
+    stateField?: string;
+}
+/** A parsed kind convention: the governed `type` plus its declared shape. */
+export interface KindConvention {
+    /** Concept id of the convention doc itself (e.g. `conventions/roadmap-item`). */
+    id: ConceptId;
+    /** Display title (defaults to `governs` when the convention doc omits one). */
+    title: string;
+    /** The `type` value this convention governs (required, non-empty — malformed docs are skipped). */
+    governs: string;
+    /** Human-readable purpose and intended use of this kind. */
+    description?: string;
+    /** Canonical bundle-relative path prefix for instances of this kind, if declared. */
+    path?: string;
+    fields: KindFields;
+    /**
+     * The typed-edge vocabulary this kind declares as link SOURCE: `link type name -> allowed
+     * target kind` (decision `decisions/typed-links-carrier`, 2026-07-07: a link whose display
+     * text exactly matches a declared type is a typed edge; every other link is an untyped
+     * citation). Discovery-only at this layer — write-time validation is a future consumer.
+     */
+    links?: Record<string, string>;
+    /** Human guidance for declared outbound relationships: `link type name -> description`. */
+    linkDescriptions?: Record<string, string>;
+    /**
+     * Inbound-link expectations this kind declares on ITSELF as link TARGET: `link type name ->
+     * expected SOURCE kind` (e.g. a `Task` declaring `expects_inbound: {contains: "Roadmap Item"}`
+     * means every Task instance is expected to carry at least one inbound edge whose text is
+     * exactly `contains` from a doc of type `Roadmap Item`). Discovery-only at this layer — the
+     * `status` graph-lint sweep (`missing_expected_links`) is the write-side consumer; write-time
+     * validation is never enforced by this key.
+     */
+    expectsInbound?: Record<string, string>;
+    /** Expected body-section headings (level-1 `# Heading`), if declared. Scaffold + lint only. */
+    sections?: string[];
+    /** Raw declared horizon string (`<n>(m|h|d)`), if present — parse via {@link freshnessHorizonMs}. */
+    freshnessHorizon?: string;
+    /**
+     * Browse/listing display hint: when `true`, a browse UI collapses this kind's instances behind a
+     * toggle by default — for a transient/background kind (e.g. Context Note) whose volume would
+     * otherwise swamp durable knowledge. Absent → expanded. Bundle-DECLARED so the shell never
+     * privileges a kind by name; display-only, no engine behavior. Set from `browse_collapsed: true`.
+     */
+    browseCollapsed?: boolean;
+    /**
+     * The bundle-declared claim vocabulary, when this kind declares one. Absent for every kind that
+     * does not — a bundle with no `claim:` declaration behaves exactly as it did before the key
+     * existed.
+     */
+    claim?: KindClaimPolicy;
+}
+/** The result of {@link loadKinds}: the built registry plus any non-fatal warnings collected along the way. */
+export interface KindRegistry {
+    /** `governs -> KindConvention`. On a duplicate `governs`, the first-by-id declaration wins. */
+    kinds: Map<string, KindConvention>;
+    /** Malformed/duplicate/unparseable conventions are SKIPPED, never thrown — collected here instead. */
+    warnings: ValidationWarning[];
+}
+/**
+ * Build the one authoritative Kind registry from already-selected convention documents.
+ * Callers own discovery; this pure half owns parsing, warnings, and first-by-id duplicate
+ * resolution so prospective registries cannot drift from {@link loadKinds} semantics.
+ */
+export declare function buildKindRegistry(docs: readonly OkfDocument[], initialWarnings?: readonly ValidationWarning[]): KindRegistry;
+/** Stable product-level name for a Kind's workflow progress field. */
+export declare const PROGRESS_STATUS_FIELD = "progress_status";
+/** Producer-qualified v0.2 storage coordinate for Superbee workflow progress. */
+export declare const SUPERBEE_PROGRESS_STATUS_FIELD = "superbee_progress_status";
+/** Physical coordinate used for Superbee's logical workflow-progress field in one OKF edition. */
+export declare function progressStatusStorageField(okfVersion: string | undefined): "status" | typeof SUPERBEE_PROGRESS_STATUS_FIELD | undefined;
+/** A logical Kind field and the concrete frontmatter key that stores it in this OKF edition. */
+export interface KindFieldCoordinate {
+    logicalField: string;
+    storageField: string;
+}
+/**
+ * Compile the declaration-driven workflow-progress coordinate for one Kind. Missing root version
+ * means v0.1 (OKF's compatibility default). Values never activate this mapping.
+ */
+export declare function progressStatusCoordinate(okfVersion: string | undefined, kind: KindConvention): KindFieldCoordinate | undefined;
+/** Resolve an agent-facing Kind field to its declared storage coordinate. */
+export declare function resolveKindFieldCoordinate(okfVersion: string | undefined, kind: KindConvention, field: string): KindFieldCoordinate | undefined;
+/** A kind's claim vocabulary resolved onto the frontmatter keys that actually store it. */
+export interface KindClaimCoordinates {
+    /** Storage key recording the owner, when declared AND resolvable on this kind. */
+    ownerField?: string;
+    /** Storage key recording the claim state, when declared AND resolvable on this kind. */
+    stateField?: string;
+    /** Every resolved coordinate, de-duplicated — the set a consumer compares two versions over. */
+    fields: string[];
+}
+/**
+ * Resolve a Kind's declared claim vocabulary onto this bundle edition's storage coordinates
+ * through the ONE field resolver ({@link resolveKindFieldCoordinate}), so a logical declaration
+ * (`state_field: progress_status`) lands on the edition's real key. A declared name the Kind does
+ * not actually carry resolves to NOTHING and is dropped: a consumer then compares no coordinate
+ * at all rather than a key that can never match. Undefined when the Kind declares no `claim:`
+ * block, or when nothing in it resolves.
+ */
+export declare function claimCoordinates(okfVersion: string | undefined, kind: KindConvention): KindClaimCoordinates | undefined;
+/** Declared authoring names plus the logical progress alias, when this Kind proves one exists. */
+export declare function kindInputFieldNames(okfVersion: string | undefined, kind: KindConvention): string[];
+/** Read a declared logical or physical Kind field without changing the stored frontmatter. */
+export declare function readKindField(okfVersion: string | undefined, kind: KindConvention, frontmatter: Frontmatter, field: string): unknown;
+/**
+ * Add logical field aliases to a product-facing projection while preserving every raw key. Generic
+ * document reads remain raw; only Kind-aware product surfaces call this helper.
+ */
+export declare function projectLogicalKindFields(okfVersion: string | undefined, kind: KindConvention, frontmatter: Frontmatter): Frontmatter;
+/**
+ * Project a parsed Kind convention into Superbee's authoring vocabulary. Stored convention bytes
+ * remain untouched; product-facing schema/help surfaces use this view so an edition-specific
+ * workflow coordinate never becomes something an author has to learn.
+ */
+export declare function projectKindForAuthoring(okfVersion: string | undefined, kind: KindConvention): KindConvention;
+/** Project Kind-validation findings into the same authoring vocabulary as the Kind schema. */
+export declare function projectKindValidationWarnings(okfVersion: string | undefined, kind: KindConvention, warnings: ValidationWarning[]): ValidationWarning[];
+/**
+ * Field names the CLI reserves for its own machinery and can never treat as a kind-declared
+ * field: `type` is stamped from `kind.governs` (a kind declaring it as a field would let
+ * `new --type <v>` silently overwrite the governed type it just validated against), and
+ * `dir`/`remote`/`json`/`help` are consumed by every command's common flag handling before a
+ * `--<field> <value>` pair ever reaches kind-field mapping. `body` and `body-file` are `new`'s
+ * complete-body inline and file channels. Declaring any of them would make the field permanently
+ * unreachable, not merely confusing. Filtered out of `required`/`optional`/`values` at parse time
+ * with a collected warning — never silently accepted.
+ */
+export declare const RESERVED_KIND_FIELD_NAMES: readonly ["type", "dir", "remote", "json", "help", "body", "body-file"];
+/** Split a body into `{ headingText: sectionContent }` by its level-1 headings. */
+export declare function splitSections(body: string): Record<string, string>;
+/** Parse one convention doc into a {@link KindConvention}, or a reason it was skipped. */
+export declare function parseConventionDoc(doc: OkfDocument): ({
+    ok: true;
+    kind: KindConvention;
+    reservedFieldsIgnored: string[];
+    reservedFieldPaths: string[];
+} | {
+    ok: false;
+    reason: string;
+}) & {
+    warnings: ValidationWarning[];
+};
+/**
+ * Parse a kind's declared `freshness_horizon` (`<n>(m|h|d)`) to milliseconds, or
+ * `undefined` if the kind declares none or it is malformed. This FEEDS the existing
+ * {@link FreshnessOptions.maxAgeMs} at the CLI layer — it does not fork `freshness()`.
+ */
+export declare function freshnessHorizonMs(kind: KindConvention): number | undefined;
+/**
+ * True when a required-field value counts as "present" (non-empty string / non-empty array / any
+ * other defined value). Exported so consumers that must AGREE with validation's presence predicate
+ * (e.g. the CLI's `kind draft` inference) reuse this one authority instead of forking it.
+ */
+export declare function isPresent(value: unknown): boolean;
+/**
+ * Validate `doc` against `kind`: required fields present + non-empty, enum-restricted
+ * field values within the declared allowed set, and declared body `sections` present
+ * (reusing the ONE heading splitter, {@link splitSections} — no second heading parser).
+ * Returns core's EXISTING {@link ValidationWarning} shape; never throws. Purely
+ * additive derivation — callers (the CLI) decide whether a warning blocks a write.
+ */
+export declare function validateAgainstKind(doc: OkfDocument, kind: KindConvention): ValidationWarning[];
+/** Result of validating a document through a bundle's already-loaded kind registry. */
+export interface RegistryValidationResult {
+    /** The governing kind, when the document's type is declared in this registry. */
+    kind?: KindConvention;
+    warnings: ValidationWarning[];
+}
+/**
+ * Apply edition-aware legacy timestamp defaulting before evaluating the governing kind. v0.1
+ * retains the historical default on every write; v0.2 defaults it only when the bundle-local Kind
+ * explicitly requires that extension. The registry is supplied by the caller so mutation does
+ * not perform hidden discovery.
+ */
+export declare function defaultTimestampAndValidateAgainstRegistry(doc: OkfDocument, registry: KindRegistry, options?: {
+    okfVersion?: string;
+    now?: () => string;
+}): RegistryValidationResult;
+/**
+ * True iff `frontmatter` carries a terminal value on any field `kind.fields.terminal` declares
+ * (task board `tasks/status-terminal-declaration.md`) — THE one derivation every consumer calls
+ * (list's `--open`, the `status` sweep's exclusion + sort fallback). Coercion mirrors
+ * `validateAgainstKind`'s enum check: `String(v)` per element, so an unquoted YAML scalar still
+ * matches, and an array field matches on ANY-member semantics: ONE terminal value anywhere in an
+ * array field marks the whole doc terminal (a doc with `status: [done, doing]` IS terminal), so
+ * multi-valued fields should only declare terminal values whose mere presence means "closed". A
+ * kind with an empty `fields.terminal` (no declaration), or a doc missing every declared terminal
+ * field, is never terminal — not-terminal is the safe default.
+ */
+export declare function isTerminal(kind: KindConvention, frontmatter: Frontmatter): boolean;
+/**
+ * Build the OKF concept document for a kind convention (the shape a `Convention` doc
+ * takes on disk — used to serialize any KindConvention to its on-disk Convention-doc form
+ * (e.g. by the CLI's recipe machinery)). `timestamp` is the caller's ISO instant (kept
+ * explicit rather than defaulted here, since `writeDocVersioned` already guarantees one).
+ */
+export declare function kindConventionDoc(kind: KindConvention, prose: string, timestamp: string): OkfDocument;
+//# sourceMappingURL=kinds.d.ts.map

package/dist/kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.d.ts","sourceRoot":"","sources":["../src/kinds.ts"],"names":[],"mappings":"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"}