@metaobjectsdev/sdk 0.15.17 → 0.15.18-rc.1

package/agent-context/skills/metaobjects-audit/references/capability-checklist.md

@@ -89,11 +89,18 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 
 - **`identity.primary`** (`@generation`) — hunt hand-assigned primary keys / ID generation
   the primary identity's `@generation` strategy models.
-- **`identity.secondary`** (`@unique`, `@where`, `@expr`) — hunt raw-SQL partial or functional
-  unique indexes a secondary identity with `@where` / `@expr` describes.
+- **`identity.secondary`** (`@fields`; physical escapes `@using`/`@expr`/`@where`/`@orders`) — a
+  UNIQUE alternate key (uniqueness is the type — the legacy `@unique` attr was removed from it);
+  hunt hand-rolled unique constraints or raw-SQL partial/functional unique indexes it models.
 - **`identity.reference`** (`@references`, `@enforce`) — hunt hand-written FK constraints /
   reference enforcement the reference identity already declares.
 
+## Index — `index.*` (non-unique retrieval)
+
+- **`index.lookup`** (`@fields` required; physical escapes `@using`/`@expr`/`@where`/`@orders`) —
+  a NON-unique retrieval index (uniqueness is what distinguishes it from `identity.secondary`);
+  hunt hand-created lookup / recency indexes (`CREATE INDEX …`) it models.
+
 ## Origin — `origin.*` (projection-field derivation)
 
 - **`origin.aggregate`** (`@agg`, `@of`, `@via`) — hunt hand `COUNT` / `SUM` / `AVG`

package/agent-context/skills/metaobjects-codegen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metaobjects-codegen
-description: Use when configuring or running MetaObjects code generation: generators/targets/dialect config, the gen command, and hand-edit-preserving regeneration.
+description: Use when configuring or running MetaObjects code generation — generators/targets/dialect config, the gen command, and hand-edit-preserving regeneration.
 ---
 
 # MetaObjects code generation

package/agent-context/skills/metaobjects-codegen/references/csharp.md

@@ -20,13 +20,12 @@ command is `dotnet-meta`).
 ## Run
 
 ```bash
-dotnet meta gen \
-  --metadata-dir metaobjects \
-  --output-dir Generated \
+dotnet meta gen metaobjects \
+  --out Generated \
   --namespace Acme.Generated
 dotnet meta gen --list                      # list registered generators
-dotnet meta gen --generators entity,db-context,routes   # select a subset
-dotnet meta verify --codegen                # codegen-drift gate (regenerate + diff vs committed)
+dotnet meta gen metaobjects --out Generated --generators entity,db-context,routes   # select a subset
+dotnet meta verify metaobjects --codegen --out Generated   # codegen-drift gate (regenerate + diff vs committed)
 ```
 
 `dotnet meta verify` defaults to `--templates` (the FR-004 prompt/template drift
@@ -82,6 +81,8 @@ consuming fields reference a hand-written/third-party enum, and the C# namespace
 
 ## Re-scaffold this context
 
-`dotnet meta agent-docs --server csharp [--out <dir>]` (re)scaffolds the slim
-always-on Markdown + these `metaobjects-*` skills into the project — the C# tool
-bundles the agent-context tree, so a C# consumer needs no Node `meta`.
+Agent-context scaffolding is owned by the Node `meta` CLI (ADR-0015). `dotnet meta
+agent-docs` only prints a redirect and exits non-zero — it does **not** scaffold.
+(Re)scaffold the slim always-on Markdown + these `metaobjects-*` skills with
+`npx meta agent-docs --server csharp [--client <fw>] [--out <dir>]`. A C# consumer
+needs Node `meta` (npx) for this one scaffold step; codegen + verify stay on `dotnet meta`.

package/agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -32,7 +32,11 @@ comes from `@metaobjectsdev/cli`; the generators come from their packages.
 
 ```ts
 import { defineConfig } from "@metaobjectsdev/cli";
-import { entityFile, queriesFile, routesFile, barrel } from "@metaobjectsdev/codegen-ts/generators";
+// Owned generators scaffolded by `meta init` (ADR-0034 scaffold-and-own).
+import { entityFile } from "./codegen/generators/entity";
+import { queriesFile } from "./codegen/generators/queries";
+import { routesFile } from "./codegen/generators/routes";
+import { barrel } from "./codegen/generators/barrel";
 import { formFile } from "@metaobjectsdev/codegen-ts-react";
 import { tanstackQuery, tanstackGrid } from "@metaobjectsdev/codegen-ts-tanstack";
 

package/agent-context/skills/metaobjects-prompts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metaobjects-prompts
-description: Use when declaring or using MetaObjects prompt construction: template.prompt/template.output, typed payload projections, provider-resolved text, deterministic render, prompt-drift verify, and parser-on-receipt.
+description: Use when declaring or using MetaObjects prompt construction — template.prompt/template.output, typed payload projections, provider-resolved text, deterministic render, prompt-drift verify, and parser-on-receipt.
 ---
 
 # MetaObjects prompt construction

package/agent-context/skills/metaobjects-runtime-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metaobjects-runtime-ui
-description: Use when wiring MetaObjects generated code into an app: runtime queries/CRUD, REST routes, and the web client (forms, grids, filters).
+description: Use when wiring MetaObjects generated code into an app — runtime queries/CRUD, REST routes, and the web client (forms, grids, filters).
 ---
 
 # Wiring MetaObjects runtime + web client

package/agent-context/skills/metaobjects-runtime-ui/references/react.md

@@ -33,7 +33,10 @@ validation rule) rides along automatically:
 ```ts
 // metaobjects.config.ts
 import { defineConfig } from "@metaobjectsdev/cli";
-import { entityFile, queriesFile, barrel } from "@metaobjectsdev/codegen-ts/generators";
+// Owned generators scaffolded by `meta init` (ADR-0034 scaffold-and-own).
+import { entityFile } from "./codegen/generators/entity";
+import { queriesFile } from "./codegen/generators/queries";
+import { barrel } from "./codegen/generators/barrel";
 import { formFile } from "@metaobjectsdev/codegen-ts-react";
 
 export default defineConfig({

package/agent-context/skills/metaobjects-runtime-ui/references/tanstack.md

@@ -75,11 +75,11 @@ projections):
 
 | Hook | Verb / Path |
 |---|---|
-| `useAuthor(id)` | `GET /api/author/:id` |
-| `useAuthors(filter?)` | `GET /api/author?filter[..]=..&sort=..&limit=N&offset=N` |
-| `useCreateAuthor()` | `POST /api/author` |
-| `useUpdateAuthor()` | `PATCH /api/author/:id` |
-| `useDeleteAuthor()` | `DELETE /api/author/:id` |
+| `useAuthor(id)` | `GET /api/authors/:id` |
+| `useAuthors(filter?)` | `GET /api/authors?filter[..]=..&sort=..&limit=N&offset=N` |
+| `useCreateAuthor()` | `POST /api/authors` |
+| `useUpdateAuthor()` | `PATCH /api/authors/:id` |
+| `useDeleteAuthor()` | `DELETE /api/authors/:id` |
 
 Query hooks return `UseQueryResult`; mutation hooks return `UseMutationResult` and
 invalidate the entity's query keys so lists re-fetch after writes.

package/agent-context/skills/metaobjects-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metaobjects-verify
-description: Use when verifying MetaObjects: drift checks (verify --db/--codegen/--templates), schema migrations, and interpreting conformance/test failures.
+description: Use when verifying MetaObjects — drift checks (verify --db/--codegen/--templates), schema migrations, and interpreting conformance/test failures.
 ---
 
 # MetaObjects verify + migrations

package/agent-context/skills/metaobjects-verify/references/migration.md

@@ -105,16 +105,25 @@ DB didn't follow.
 
 ## Index modeling (Postgres)
 
-Secondary indexes carry physical-shape attributes contributed by the db provider
-(they live on `identity.secondary`, not core):
+Two index types, distinguished by uniqueness (ADR-0040) — both carry the same
+physical-shape escapes contributed by the db provider:
+
+- **`identity.secondary`** — a UNIQUE alternate key (uniqueness is the type; the legacy
+  `@unique` attr was removed from it).
+- **`index.lookup`** — a NON-unique retrieval index (`@fields` required).
+
+Shared physical escapes:
 
 - `@orders` — per-key sort direction, positional to `@fields` (`["asc", "desc"]`).
   Omit for all-ascending; drives `DESC`-ordered index keys (e.g. a recency index).
 - `@where` — a partial-index predicate (raw SQL, e.g. `"delivered_at IS NULL"`),
   emitted as `WHERE (<pred>)`. The index then covers only matching rows.
+- `@using` / `@expr` — index method and functional-expression escapes.
+
+A non-unique recency index is `index.lookup`:
 
 ```json
-{ "identity.secondary": { "@fields": ["userId", "createdAt"],
+{ "index.lookup": { "@fields": ["userId", "createdAt"],
     "@orders": ["asc", "desc"], "@where": "archived_at IS NULL" } }
 ```
 

package/dist/agent-context/assemble.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAiCzE,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAAG,aAAa,EAAE,CAsCrF"}
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/agent-context/assemble.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgD,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAqC1G,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAAG,aAAa,EAAE,CAyCrF"}

package/dist/agent-context/assemble.js

@@ -1,6 +1,9 @@
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { SKILL_NAMES } from "./types.js";
+import { SKILL_NAMES, SERVER_LANGS, CLIENT_FRAMEWORKS } from "./types.js";
+// Language/framework reference fragments are stack-scoped; any other fragment
+// (e.g. capability-checklist) is universal and always installs.
+const LANGUAGE_FRAGMENT_TOKENS = new Set([...SERVER_LANGS, ...CLIENT_FRAMEWORKS]);
 function readServerMeta(contentRoot, server) {
     const p = join(contentRoot, "servers", `${server}.meta.json`);
     if (!existsSync(p))
@@ -46,14 +49,18 @@ export function assemble(opts) {
         out.push({ path: `.claude/skills/${skill}/SKILL.md`, contents: body });
         const refDir = join(skillDir, "references");
         if (existsSync(refDir) && statSync(refDir).isDirectory()) {
-            // Deploy-all: every reference fragment is installed; the agent reads the
-            // one(s) matching its stack (SKILL.md points to them). Robust to
-            // stack-detection misses — a narrow/empty stack never starves the agent.
+            // Stack-scoped: a language/framework fragment installs only when its token
+            // is in the resolved stack (Stack.tokens = servers ∪ clients ∪ {migration}).
+            // Non-language fragments (e.g. capability-checklist) are universal and always
+            // install. Keeps each skill's references/ to what the project actually uses,
+            // so the SKILL.md "read every references/*.md" footer stays accurate.
             const refs = readdirSync(refDir)
                 .filter((f) => f.endsWith(".md"))
                 .map((f) => f.replace(/\.md$/, ""))
                 .sort();
             for (const token of refs) {
+                if (LANGUAGE_FRAGMENT_TOKENS.has(token) && !stack.tokens.has(token))
+                    continue;
                 out.push({
                     path: `.claude/skills/${skill}/references/${token}.md`,
                     contents: readFileSync(join(refDir, `${token}.md`), "utf8"),

package/dist/agent-context/assemble.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.15.17",
+  "version": "0.15.18-rc.1",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.15.17",
+    "@metaobjectsdev/metadata": "0.15.18-rc.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/src/agent-context/assemble.ts

@@ -1,6 +1,10 @@
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { SKILL_NAMES, type AssembledFile, type Stack } from "./types.js";
+import { SKILL_NAMES, SERVER_LANGS, CLIENT_FRAMEWORKS, type AssembledFile, type Stack } from "./types.js";
+
+// Language/framework reference fragments are stack-scoped; any other fragment
+// (e.g. capability-checklist) is universal and always installs.
+const LANGUAGE_FRAGMENT_TOKENS = new Set<string>([...SERVER_LANGS, ...CLIENT_FRAMEWORKS]);
 
 interface ServerMeta { displayName: string; install: string; codegenCommand: string; }
 
@@ -53,14 +57,17 @@ export function assemble(opts: { contentRoot: string; stack: Stack }): Assembled
 
     const refDir = join(skillDir, "references");
     if (existsSync(refDir) && statSync(refDir).isDirectory()) {
-      // Deploy-all: every reference fragment is installed; the agent reads the
-      // one(s) matching its stack (SKILL.md points to them). Robust to
-      // stack-detection misses — a narrow/empty stack never starves the agent.
+      // Stack-scoped: a language/framework fragment installs only when its token
+      // is in the resolved stack (Stack.tokens = servers ∪ clients ∪ {migration}).
+      // Non-language fragments (e.g. capability-checklist) are universal and always
+      // install. Keeps each skill's references/ to what the project actually uses,
+      // so the SKILL.md "read every references/*.md" footer stays accurate.
       const refs = readdirSync(refDir)
         .filter((f) => f.endsWith(".md"))
         .map((f) => f.replace(/\.md$/, ""))
         .sort();
       for (const token of refs) {
+        if (LANGUAGE_FRAGMENT_TOKENS.has(token) && !stack.tokens.has(token)) continue;
         out.push({
           path: `.claude/skills/${skill}/references/${token}.md`,
           contents: readFileSync(join(refDir, `${token}.md`), "utf8"),