@metaobjectsdev/sdk 0.5.0-rc.1

package/src/forge-types.ts

@@ -0,0 +1,167 @@
+// Meta Forge type + attribute name constants. Centralized for typo-safety
+// per CLAUDE.md ("Named constants for metamodel strings — always") and so
+// downstream readers (codegen prompts, MCP exposers) have one source of
+// truth. See SP5 §4 for the design rationale.
+
+// ---------------------------------------------------------------------------
+// New top-level types registered by registerForgeTypes()
+// ---------------------------------------------------------------------------
+
+export const FORGE_TYPE_DECISION = "decision";
+export const FORGE_TYPE_PRINCIPLE = "principle";
+export const FORGE_TYPE_CONVENTION = "convention";
+export const FORGE_TYPE_GLOSSARY = "glossary";
+export const FORGE_TYPE_FAILURE = "failure";
+
+export const FORGE_TYPES = [
+  FORGE_TYPE_DECISION,
+  FORGE_TYPE_PRINCIPLE,
+  FORGE_TYPE_CONVENTION,
+  FORGE_TYPE_GLOSSARY,
+  FORGE_TYPE_FAILURE,
+] as const;
+export type ForgeType = (typeof FORGE_TYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Subtypes per type (open lists; "base" is always valid)
+// ---------------------------------------------------------------------------
+
+export const FORGE_DECISION_SUBTYPES = ["base", "global", "scoped"] as const;
+export const FORGE_PRINCIPLE_SUBTYPES = ["base", "advisory", "enforced"] as const;
+export const FORGE_CONVENTION_SUBTYPES = ["base"] as const;
+export const FORGE_GLOSSARY_SUBTYPES = ["base"] as const;
+export const FORGE_FAILURE_SUBTYPES = ["base"] as const;
+
+// ---------------------------------------------------------------------------
+// @forge* attribute names (camelCase, no separator)
+// ---------------------------------------------------------------------------
+
+// Universal (any forge-related node)
+export const FORGE_ATTR_CONFIDENCE = "forgeConfidence";
+export const FORGE_ATTR_SOURCE = "forgeSource";
+export const FORGE_ATTR_CAPTURED_AT = "forgeCapturedAt";
+export const FORGE_ATTR_LAST_VALIDATED_COMMIT = "forgeLastValidatedCommit";
+
+// Object/entity
+export const FORGE_ATTR_PRIMARY_LOCATION = "forgePrimaryLocation";
+export const FORGE_ATTR_OCCURRENCES = "forgeOccurrences";
+
+// Decision
+export const FORGE_ATTR_RATIONALE = "forgeRationale";
+export const FORGE_ATTR_ALTERNATIVES = "forgeAlternatives";
+export const FORGE_ATTR_SCOPE = "forgeScope";
+
+// Principle
+export const FORGE_ATTR_STATEMENT = "forgeStatement";
+export const FORGE_ATTR_ENFORCEMENT = "forgeEnforcement";
+
+// Convention
+export const FORGE_ATTR_PATTERN_DESCRIPTION = "forgePatternDescription";
+export const FORGE_ATTR_EXAMPLES = "forgeExamples";
+export const FORGE_ATTR_COUNTER_EXAMPLES = "forgeCounterExamples";
+export const FORGE_ATTR_APPLIES_TO = "forgeAppliesTo";
+
+// Glossary
+export const FORGE_ATTR_TERM = "forgeTerm";
+export const FORGE_ATTR_SYNONYMS = "forgeSynonyms";
+export const FORGE_ATTR_DEFINITION = "forgeDefinition";
+export const FORGE_ATTR_CODE_ANCHORS = "forgeCodeAnchors";
+export const FORGE_ATTR_SEE_ALSO = "forgeSeeAlso";
+
+// Failure
+export const FORGE_ATTR_WHAT_WAS_TRIED = "forgeWhatWasTried";
+export const FORGE_ATTR_WHY_IT_FAILED = "forgeWhyItFailed";
+
+export const FORGE_ATTRS = [
+  FORGE_ATTR_CONFIDENCE,
+  FORGE_ATTR_SOURCE,
+  FORGE_ATTR_CAPTURED_AT,
+  FORGE_ATTR_LAST_VALIDATED_COMMIT,
+  FORGE_ATTR_PRIMARY_LOCATION,
+  FORGE_ATTR_OCCURRENCES,
+  FORGE_ATTR_RATIONALE,
+  FORGE_ATTR_ALTERNATIVES,
+  FORGE_ATTR_SCOPE,
+  FORGE_ATTR_STATEMENT,
+  FORGE_ATTR_ENFORCEMENT,
+  FORGE_ATTR_PATTERN_DESCRIPTION,
+  FORGE_ATTR_EXAMPLES,
+  FORGE_ATTR_COUNTER_EXAMPLES,
+  FORGE_ATTR_APPLIES_TO,
+  FORGE_ATTR_TERM,
+  FORGE_ATTR_SYNONYMS,
+  FORGE_ATTR_DEFINITION,
+  FORGE_ATTR_CODE_ANCHORS,
+  FORGE_ATTR_SEE_ALSO,
+  FORGE_ATTR_WHAT_WAS_TRIED,
+  FORGE_ATTR_WHY_IT_FAILED,
+] as const;
+export type ForgeAttr = (typeof FORGE_ATTRS)[number];
+
+// ---------------------------------------------------------------------------
+// registerForgeTypes
+// ---------------------------------------------------------------------------
+
+import {
+  type ChildRule,
+  type TypeDefinition,
+  TypeId,
+  TypeRegistry,
+  MetaData,
+  TYPE_ATTR,
+  CHILD_RULE_WILDCARD,
+} from "@metaobjectsdev/metadata";
+
+/** Minimal concrete MetaData subclass used for all forge descriptive nodes. */
+class MetaForgeNode extends MetaData {}
+
+function wildcardOf(childType: string): ChildRule {
+  return {
+    childType,
+    childSubType: CHILD_RULE_WILDCARD,
+    childName: CHILD_RULE_WILDCARD,
+  };
+}
+
+function def(
+  type: string,
+  subType: string,
+  description: string,
+  childRules: ChildRule[],
+): TypeDefinition {
+  return {
+    typeId: new TypeId(type, subType),
+    description,
+    factory: (typeId, name) => new MetaForgeNode(typeId, name),
+    childRules,
+    attributes: [],
+  };
+}
+
+/**
+ * Register Meta Forge's five descriptive top-level types into the given
+ * registry. Must be called AFTER `registerCoreTypes()`.
+ *
+ * Each type accepts `attr` children for expanded-form @forge* attributes.
+ * Loader's default permissive mode tolerates these new types as children
+ * of the metadata wrapper (unknowns are warned, not errored).
+ */
+export function registerForgeTypes(registry: TypeRegistry): void {
+  const forgeChildRules = [wildcardOf(TYPE_ATTR)];
+
+  for (const subType of FORGE_DECISION_SUBTYPES) {
+    registry.register(def(FORGE_TYPE_DECISION, subType, `Forge decision (${subType})`, forgeChildRules));
+  }
+  for (const subType of FORGE_PRINCIPLE_SUBTYPES) {
+    registry.register(def(FORGE_TYPE_PRINCIPLE, subType, `Forge principle (${subType})`, forgeChildRules));
+  }
+  for (const subType of FORGE_CONVENTION_SUBTYPES) {
+    registry.register(def(FORGE_TYPE_CONVENTION, subType, `Forge convention (${subType})`, forgeChildRules));
+  }
+  for (const subType of FORGE_GLOSSARY_SUBTYPES) {
+    registry.register(def(FORGE_TYPE_GLOSSARY, subType, `Forge glossary entry (${subType})`, forgeChildRules));
+  }
+  for (const subType of FORGE_FAILURE_SUBTYPES) {
+    registry.register(def(FORGE_TYPE_FAILURE, subType, `Forge failure record (${subType})`, forgeChildRules));
+  }
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+// Records
+export { RecordCore, RecordType, RecordSource } from "./records/core.js";
+export { ConventionRecord } from "./records/convention.js";
+export { DecisionRecord } from "./records/decision.js";
+export { PrincipleRecord } from "./records/principle.js";
+export { GlossaryRecord } from "./records/glossary.js";
+export { FailureRecord } from "./records/failure.js";
+export { AnyRecord } from "./records/any.js";
+
+// Storage
+export {
+  readRecord,
+  recordExists,
+  writeRecord,
+  removeRecord,
+  listRecords,
+  promoteRecord,
+  supersede,
+  MetaForgeRecordNotFoundError,
+  MetaForgeAlreadyPromotedError,
+  MetaForgeRecordParseError,
+} from "./storage/index.js";
+export type { ListOptions } from "./storage/index.js";
+
+// Paths
+export { recordPath, resolveMetaRoot } from "./paths.js";
+
+// Config
+export { ConfigSchema, DEFAULT_CONFIG, loadConfig, saveConfig } from "./config.js";
+export type { Config } from "./config.js";
+
+// Meta Forge metadata types + attribute name constants (registered into a
+// TypeRegistry to let Loader parse decision/principle/etc. children + the
+// @forge* attribute namespace).
+export {
+  // Type names
+  FORGE_TYPE_DECISION,
+  FORGE_TYPE_PRINCIPLE,
+  FORGE_TYPE_CONVENTION,
+  FORGE_TYPE_GLOSSARY,
+  FORGE_TYPE_FAILURE,
+  FORGE_TYPES,
+  // Subtypes
+  FORGE_DECISION_SUBTYPES,
+  FORGE_PRINCIPLE_SUBTYPES,
+  FORGE_CONVENTION_SUBTYPES,
+  FORGE_GLOSSARY_SUBTYPES,
+  FORGE_FAILURE_SUBTYPES,
+  // Attribute names
+  FORGE_ATTR_CONFIDENCE,
+  FORGE_ATTR_SOURCE,
+  FORGE_ATTR_CAPTURED_AT,
+  FORGE_ATTR_LAST_VALIDATED_COMMIT,
+  FORGE_ATTR_PRIMARY_LOCATION,
+  FORGE_ATTR_OCCURRENCES,
+  FORGE_ATTR_RATIONALE,
+  FORGE_ATTR_ALTERNATIVES,
+  FORGE_ATTR_SCOPE,
+  FORGE_ATTR_STATEMENT,
+  FORGE_ATTR_ENFORCEMENT,
+  FORGE_ATTR_PATTERN_DESCRIPTION,
+  FORGE_ATTR_EXAMPLES,
+  FORGE_ATTR_COUNTER_EXAMPLES,
+  FORGE_ATTR_APPLIES_TO,
+  FORGE_ATTR_TERM,
+  FORGE_ATTR_SYNONYMS,
+  FORGE_ATTR_DEFINITION,
+  FORGE_ATTR_CODE_ANCHORS,
+  FORGE_ATTR_SEE_ALSO,
+  FORGE_ATTR_WHAT_WAS_TRIED,
+  FORGE_ATTR_WHY_IT_FAILED,
+  FORGE_ATTRS,
+  // Registration helper
+  registerForgeTypes,
+} from "./forge-types.js";
+export type { ForgeType, ForgeAttr } from "./forge-types.js";
+
+// Memory loader — read metaobjects/ into a MetaData tree
+// (workspace-aware: walks extends: deps via pnpm-workspace.yaml or
+//  package.json workspaces field if present)
+export { loadMemory, DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./memory.js";
+
+// Workspace discovery — finds peer metadata packages in a monorepo
+export { discoverWorkspace, resolveExtendsOrder, packageLabel } from "./workspace.js";
+export type { Workspace, WorkspacePackage } from "./workspace.js";
+
+// Package manifest — the v0.3 package.meta.json model. Three-field manifest
+// (name, version, extends) that defines a metadata package's identity and
+// upstream dependencies. The package's metadata tree IS its public API;
+// there is no exports field. See docs/strategy/2026-05-12-v0.3-ai-first-
+// metadata-loading.md.
+export {
+  PackageManifestSchema,
+  readPackageManifest,
+  resolveMetaobjectsPackage,
+  PACKAGE_MANIFEST_FILE,
+} from "./package.js";
+export type { PackageManifest } from "./package.js";

package/src/memory.ts

@@ -0,0 +1,116 @@
+import { join } from "node:path";
+import { readdir, stat } from "node:fs/promises";
+import { FileMetaDataLoader } from "@metaobjectsdev/metadata/core";
+import {
+  TypeRegistry,
+  registerCoreTypes,
+  type MetaRoot,
+} from "@metaobjectsdev/metadata";
+import { registerForgeTypes } from "./forge-types.js";
+import { discoverWorkspace, resolveExtendsOrder } from "./workspace.js";
+
+/**
+ * Default directory name (relative to project root) where metadata JSON files
+ * are scanned. Scaffold via `meta init`; the directory is committed to git.
+ */
+export const DEFAULT_METADATA_DIR = "metaobjects";
+
+/**
+ * Default directory name (relative to project root) for MetaObjects' own
+ * runtime state: config.json, .gen-state/, package.meta.json, agent docs.
+ * Scaffold via `meta init`; most contents are committed to git.
+ */
+export const DEFAULT_METAOBJECTS_DIR = ".metaobjects";
+
+/**
+ * Load all metadata files from `<repoRoot>/metaobjects/` into a single
+ * MetaData. If `<repoRoot>/.meta/package.meta.json` declares `extends:` deps
+ * and a workspace can be discovered (pnpm-workspace.yaml or package.json
+ * workspaces), peer packages are loaded too in topological dep-first order.
+ *
+ * Excludes `_pending/`. Registers metaobjects core types plus Meta Forge's
+ * descriptive top-level types (decision, principle, etc.) so mixed content
+ * parses without warnings.
+ *
+ * Throws if `metaobjects/` doesn't exist (callers should run `meta init`).
+ *
+ * @param repoRoot The project's working-directory root (e.g. process.cwd()).
+ *   `loadMemory` resolves `metaobjects/` and (if workspace-aware) the
+ *   transitive `extends:` graph automatically.
+ */
+export async function loadMemory(repoRoot: string): Promise<MetaRoot> {
+  const registry = new TypeRegistry();
+  registerCoreTypes(registry);
+  registerForgeTypes(registry);
+
+  // Collect all metadata file paths to load. Order matters for the parser's
+  // deferred-resolution pass (it parses in array order, then resolves supers
+  // against the merged tree afterwards) — dep packages first, current last.
+  const paths = await collectMetadataPaths(repoRoot);
+
+  const loader = new FileMetaDataLoader({ registry });
+  const result = await loader.loadFiles(paths);
+
+  if (result.errors.length > 0) {
+    const first = result.errors[0]!;
+    throw first;
+  }
+
+  return result.root;
+}
+
+// Dep packages' metaobjects/ files first (topological order), then current.
+async function collectMetadataPaths(repoRoot: string): Promise<string[]> {
+  const currentMetaDir = join(repoRoot, ".meta");
+  const ws = await discoverWorkspace(repoRoot);
+
+  // Workspace path: walk extends, load dep metaobjects/ dirs first
+  if (ws !== undefined) {
+    const currentPkg = ws.packages.find((p) => p.metaDir === currentMetaDir);
+    if (currentPkg !== undefined && currentPkg.manifest.extends.length > 0) {
+      const ordered = resolveExtendsOrder(ws, currentMetaDir);
+      const paths: string[] = [];
+      for (const pkg of ordered) {
+        // Each workspace package's metadata lives alongside its .meta/ dir
+        const pkgRoot = join(pkg.metaDir, "..");
+        paths.push(...(await listJsonFiles(join(pkgRoot, DEFAULT_METADATA_DIR))));
+      }
+      return paths;
+    }
+  }
+
+  // Single-package path: scan metaobjects/ at the project root
+  return listJsonFiles(join(repoRoot, DEFAULT_METADATA_DIR));
+}
+
+/**
+ * Recursively list *.json files under a directory, excluding _pending/ at
+ * any level. Subdirectories (e.g. projections/) are walked depth-first.
+ * Files within a directory are sorted alphabetically for deterministic load
+ * order; subdirectories are visited after files at the same level.
+ */
+async function listJsonFiles(dir: string): Promise<string[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch (err) {
+    throw new Error(`loadMemory: cannot read ${dir}: ${(err as Error).message}`);
+  }
+  const paths: string[] = [];
+  const subdirs: string[] = [];
+  for (const entry of entries) {
+    if (entry === "_pending") continue;
+    const full = join(dir, entry);
+    const s = await stat(full);
+    if (s.isDirectory()) {
+      subdirs.push(full);
+    } else if (s.isFile() && entry.endsWith(".json")) {
+      paths.push(full);
+    }
+  }
+  // Recurse into subdirectories after collecting files at this level
+  for (const sub of subdirs.sort()) {
+    paths.push(...(await listJsonFiles(sub)));
+  }
+  return paths;
+}

package/src/package.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+// Per the v0.3 AI-first metadata loading strategy: a package.meta.json is the
+// boundary between metadata bundles. Three fields total — name, version,
+// extends. No exports list; no @private. The package's metadata tree IS its
+// public API. See docs/strategy/2026-05-12-v0.3-ai-first-metadata-loading.md
+// §4.3.
+
+/**
+ * Validates a package version string. npm-compatible: semver basics
+ * (major.minor.patch with optional prerelease/build). Not a full semver
+ * parser — strict-enough for now.
+ */
+const VersionStringSchema = z.string().regex(
+  /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/,
+  "package version must follow semver (e.g. 1.2.0 or 1.2.0-alpha.1)",
+);
+
+/**
+ * Validates a package extends entry. Either a bare package name or
+ * a name with a semver range — npm-style. Range parsing is shallow
+ * for v0.3 v0.1; full range resolution lands when multi-package
+ * loading actually ships.
+ */
+const ExtendsEntrySchema = z.string().min(1);
+
+/**
+ * Validates a canonical metaobjects package ref: snake_case segments
+ * separated by `::`. Examples: `trainer_website`, `acme::common::user_mgmt`.
+ * Used in metadata file refs (extends:, super:) cross-language.
+ */
+const MetaobjectsPackageSchema = z.string().regex(
+  /^[a-z][a-z0-9_]*(::[a-z][a-z0-9_]*)*$/,
+  "metaobjectsPackage must be snake_case segments separated by :: (e.g. acme::common::user_mgmt)",
+);
+
+/**
+ * The package.meta.json schema. Authoring this is the one-time cost of
+ * defining a metadata package; subsequent edits should be rare.
+ */
+export const PackageManifestSchema = z.object({
+  /**
+   * Canonical name of the package in the language's native package manager.
+   * Conventionally `@scope/name` (npm-style) for TS, but bare names also
+   * work. Each language's package config (pom.xml, .csproj, pyproject.toml)
+   * uses its own native field for this — only TS uses `name` here.
+   */
+  name: z.string().min(1),
+
+  /** Semver version of this package. */
+  version: VersionStringSchema,
+
+  /**
+   * Optional cross-language canonical ref for this package, used inside
+   * metadata files (extends:, super:) and for cross-language consumption.
+   * If omitted, derived from `name` via a simple rule: `@scope/name` →
+   * `scope::name` (strip @, replace `/` with `::`). Hyphens stay as-is in
+   * the auto-derived form — for hierarchical naming users declare this
+   * field explicitly.
+   *
+   * Per v0.3 strategy doc §8.2.
+   */
+  metaobjectsPackage: MetaobjectsPackageSchema.optional(),
+
+  /**
+   * Other packages whose metadata trees this package extends. Each entry is
+   * a package name; the loader resolves it to the matching peer package.
+   * Empty/omitted means this package has no upstream dependencies.
+   */
+  extends: z.array(ExtendsEntrySchema).default([]),
+});
+
+export type PackageManifest = z.infer<typeof PackageManifestSchema>;
+
+export const PACKAGE_MANIFEST_FILE = "package.meta.json";
+
+/**
+ * Read a package.meta.json from a given .meta/ root, if present.
+ * Returns undefined when the file isn't there — packages are optional in
+ * v0.3 v0.1 (loadMemory still works for single-package usage without one,
+ * and forge init scaffolds one but doesn't enforce its presence).
+ */
+export async function readPackageManifest(metaDir: string): Promise<PackageManifest | undefined> {
+  const path = join(metaDir, PACKAGE_MANIFEST_FILE);
+  try {
+    const s = await stat(path);
+    if (!s.isFile()) return undefined;
+  } catch {
+    return undefined;
+  }
+  const raw = await readFile(path, "utf8");
+  return PackageManifestSchema.parse(JSON.parse(raw));
+}
+
+/**
+ * Return the canonical metaobjects package ref for a manifest. Uses the
+ * explicit `metaobjectsPackage` field if set; otherwise derives from `name`
+ * via the simple rule: `@scope/foo-bar` → `scope::foo-bar` (strip @,
+ * replace `/` with `::`, leave hyphens). For hierarchical or non-trivial
+ * naming users declare `metaobjectsPackage` explicitly.
+ *
+ * Returns undefined if `name` itself isn't a valid bare name (e.g. has
+ * uppercase chars) and no explicit ref is set — the caller should treat
+ * this as an authoring error.
+ */
+export function resolveMetaobjectsPackage(manifest: PackageManifest): string | undefined {
+  if (manifest.metaobjectsPackage !== undefined) return manifest.metaobjectsPackage;
+  // Auto-derive from name: strip leading @, replace / with ::, lowercase
+  // remains untouched — npm names are already lowercase per registry rules.
+  const stripped = manifest.name.replace(/^@/, "");
+  const derived = stripped.replace(/\//g, "::");
+  // Validate that the derived form is a legal canonical ref. If not,
+  // return undefined so the caller can surface a clear error.
+  if (!/^[a-z][a-z0-9_-]*(::[a-z][a-z0-9_-]*)*$/.test(derived)) {
+    return undefined;
+  }
+  return derived;
+}

package/src/paths.ts

@@ -0,0 +1,30 @@
+import { stat } from "node:fs/promises";
+import { join, dirname, resolve, parse } from "node:path";
+
+export function recordPath(
+  metaRoot: string,
+  type: string,
+  id: string,
+  opts: { pending?: boolean } = {},
+): string {
+  const segments = opts.pending
+    ? ["memory", "_pending", type, `${id}.json`]
+    : ["memory", type, `${id}.json`];
+  return join(metaRoot, ...segments);
+}
+
+export async function resolveMetaRoot(startDir: string): Promise<string> {
+  let current = resolve(startDir);
+  const root = parse(current).root;
+  while (current !== root) {
+    const candidate = join(current, ".meta");
+    try {
+      const s = await stat(candidate);
+      if (s.isDirectory()) return candidate;
+    } catch {
+      // not present at this level
+    }
+    current = dirname(current);
+  }
+  throw new Error(`no .meta directory found walking up from ${startDir}`);
+}

package/src/records/any.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { ConventionRecord } from "./convention.js";
+import { DecisionRecord } from "./decision.js";
+import { PrincipleRecord } from "./principle.js";
+import { GlossaryRecord } from "./glossary.js";
+import { FailureRecord } from "./failure.js";
+
+export const AnyRecord = z.discriminatedUnion("type", [
+  ConventionRecord,
+  DecisionRecord,
+  PrincipleRecord,
+  GlossaryRecord,
+  FailureRecord,
+]);
+export type AnyRecord = z.infer<typeof AnyRecord>;

package/src/records/convention.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { RecordCore } from "./core.js";
+
+export const ConventionRecord = RecordCore.extend({
+  type: z.literal("convention"),
+  pattern_description: z.string(),
+  examples: z.array(z.string()),
+  applies_to: z.array(z.string()),
+});
+export type ConventionRecord = z.infer<typeof ConventionRecord>;

package/src/records/core.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+
+export const RecordType = z.enum([
+  "convention",
+  "decision",
+  "principle",
+  "glossary",
+  "failure",
+]);
+export type RecordType = z.infer<typeof RecordType>;
+
+export const RecordSource = z.enum([
+  "ts-ast",
+  "drizzle",
+  "prisma",
+  "openapi",
+  "human",
+  "claude",
+  "llm-from-commits",
+  "llm-from-prs",
+  "ingest:ts-ast",
+  "ingest:drizzle",
+  "ingest:zod",
+]);
+export type RecordSource = z.infer<typeof RecordSource>;
+
+export const RecordCore = z.object({
+  schema_version: z.literal(1),
+  type: RecordType,
+  id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+  title: z.string(),
+  confidence: z.number().min(0).max(1),
+  source: RecordSource,
+  captured_at: z.string().datetime(),
+  last_validated_against_commit: z.string(),
+  superseded_by: z.string().optional(),
+  evidence: z
+    .object({
+      commits: z.array(z.string()).optional(),
+      prs: z.array(z.string()).optional(),
+      conversation_id: z.string().optional(),
+    })
+    .optional(),
+  deviations: z
+    .array(
+      z.object({
+        when: z.string().datetime(),
+        why: z.string(),
+        conversation_id: z.string().optional(),
+      }),
+    )
+    .default([]),
+});
+
+export type RecordCore = z.infer<typeof RecordCore>;

package/src/records/decision.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { RecordCore } from "./core.js";
+
+export const DecisionRecord = RecordCore.extend({
+  type: z.literal("decision"),
+  rationale: z.string(),
+  alternatives_considered: z.array(z.string()),
+  scope: z.union([z.literal("global"), z.array(z.string())]),
+});
+export type DecisionRecord = z.infer<typeof DecisionRecord>;

package/src/records/failure.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { RecordCore } from "./core.js";
+
+export const FailureRecord = RecordCore.extend({
+  type: z.literal("failure"),
+  what_was_tried: z.string(),
+  why_it_failed: z.string(),
+  do_not_repeat_in: z.array(z.string()).optional(),
+  related_decisions: z.array(z.string()).optional(),
+});
+export type FailureRecord = z.infer<typeof FailureRecord>;

package/src/records/glossary.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { RecordCore } from "./core.js";
+
+export const GlossaryRecord = RecordCore.extend({
+  type: z.literal("glossary"),
+  term: z.string(),
+  synonyms: z.array(z.string()),
+  definition: z.string(),
+  code_anchors: z.object({
+    entity: z.string().optional(),
+    files: z.array(z.string()).optional(),
+  }),
+  see_also: z.array(z.string()),
+});
+export type GlossaryRecord = z.infer<typeof GlossaryRecord>;

package/src/records/principle.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { RecordCore } from "./core.js";
+
+export const PrincipleRecord = RecordCore.extend({
+  type: z.literal("principle"),
+  statement: z.string(),
+  rationale: z.string(),
+  scope: z.array(z.string()),
+  examples: z.array(z.string()),
+  counter_examples: z.array(z.string()),
+  enforcement: z.enum(["advisory", "block"]).default("advisory"),
+});
+export type PrincipleRecord = z.infer<typeof PrincipleRecord>;