@loxtep/sdk 0.9.15 → 0.9.17

package/docs/sdk-mcp-mapping.md

@@ -14,8 +14,8 @@ deprecation aliases.
 | `loxtep_connect` | `client.connect` | `.connectors.*`, `.templates.*` |
 | `loxtep_workspace` | `client.workspace` | `.projects.*`, `.instances.*` (`list`/`get`/`create`; **`get_stream_config` is REST/CLI only** — not an MCP op). `.versions` (REST pending); planned MCP `get_project_workspace_status` → `ProjectWorkspaceStatus` ([docs](./project-workspace-status.md)) |
 | `loxtep_build` | `client.build` | `.workflows.*`, `.triggers.*`, `.data_products.*`, `.targets.*`, deploy writes, `.get_writer({ bot_id, queue })` escape hatch |
-| `loxtep_define` | `client.define` | `.schemas.*`, `.quality.*`, `.standards.*`, `.data_contracts.*`, `.domains.*` |
-| `loxtep_meaning` | `client.meaning` | `.thesaurus.*`, `.ontology.*`, `.packs.*`, `.semantic.*` (search/artifact/completeness) |
+| `loxtep_define` | `client.define` | `.schemas.*` (data-product), `.shapes.*` (domain canonical shapes), `.quality.*`, `.standards.*`, `.data_contracts.*`, `.domains.*` |
+| `loxtep_meaning` | `client.meaning` | `.thesaurus.*`, `.ontology.*`, `.packs.*`, `.semantic.*`, `.proposals.*`, `.bundles.import` |
 | `loxtep_review` | `client.review` | `.approvals.*`, `.improvements.*`, `.cdlc.*` (get/transition/propagate/lineage/deps + `list_review_queue`); `.mining.*` (`run_mining_pass`, `list_candidates`, `act_on_candidate`). CLI: `loxtep cdlc …`, `loxtep candidates list|act` |
 | `loxtep_query` | `client.query` | `.catalog.*`, `.discovery.*`, `.query()`, `.list_tables()`, `.search()` |
 | `loxtep_observe` | `client.observe` | `.status()`, `.stream_config()`, queue `.open_reader` / `.open_writer`, `.list_deployments()`, `.get_deployment()`, trust signals |
@@ -58,9 +58,31 @@ Bus physical names (`LeoCron`, `LeoS3`, …): Node `loxtep instances stream-conf
 or `client.workspace.instances.get_stream_config(id)` (Python same method). Not
 MCP `list_instances` or `get_sdk_config`.
 
+## Meaning: thesaurus / vocabulary (Phase 2)
+
+MCP `loxtep_meaning` thesaurus ops map to `client.meaning.thesaurus`:
+
+| MCP operation | SDK | REST |
+| --- | --- | --- |
+| `list_terms` | `client.meaning.thesaurus.list_terms()` | `GET /graph/organizations/{org}/thesaurus` |
+| `get_term` | `.get_term(term_id)` | `GET …/thesaurus/{term_id}` |
+| `create_term` | `.create_term({ canonical_key, aliases, … })` | `POST …/thesaurus` |
+| `update_term` | `.update_term(term_id, { … })` | `PUT …/thesaurus/{term_id}` |
+| `delete_term` | `.delete_term(term_id)` | `DELETE …/thesaurus/{term_id}` |
+| `sync_vocabulary` | `.sync_vocabulary({ domain, terms, mode, dry_run? })` | `POST …/thesaurus/sync` |
+| `create_enterprise_override` | `.create_enterprise_override({ canonical_key, enterprise_definition, divergence_reason, … })` | `POST …/thesaurus` (`is_override: true`) |
+| `resolve_canonical_key` | `.resolve_canonical_key(key_or_alias)` | client-side over `list_terms` |
+| append synonym (SDK) | `.append_synonym(canonical_key, alias_path, …)` | `POST …/thesaurus/synonyms` |
+
+MCP-only (no SDK yet): `list_enterprise_overrides`, `resolve_semantic_gap`,
+namespace-mapping CRUD (`register_namespace_mapping`, `list_namespace_mappings`,
+`get_namespace_mapping`).
+
 ## Meaning: ontology concepts (LOX-1241)
 
-MCP `loxtep_meaning` ontology ops map to `client.meaning.ontology`:
+MCP `loxtep_meaning` ontology ops map to `client.meaning.ontology`.
+`node_type` is a **lowercase** enum: `entity` \| `microservice` \| `taxonomy` \|
+`pattern` \| `custom` (not `Entity`).
 
 | MCP operation | SDK |
 | --- | --- |
@@ -74,6 +96,10 @@ MCP `loxtep_meaning` ontology ops map to `client.meaning.ontology`:
 
 REST: `/graph/organizations/{org}/ontology/concepts` and `…/relationships`.
 
+Ontology concepts are **graph types and relationships** between them. Defining
+**meaning** for agents/stewards is primarily **terms** (`thesaurus`) + **shapes**
+(`client.define.shapes`).
+
 ## Meaning: vocabulary packs (LOX-1242)
 
 These ops live under MCP **`loxtep_meaning`** / semantic-layer (not `loxtep_define`).
@@ -117,6 +143,47 @@ Notes:
 - SDK calls the semantic-layer MS REST routes directly. MCP-only enrichments (empty-search / completeness `metadata.activation_state` from pack activation) are not duplicated — use `client.meaning.packs.get_activation_status()` when needed.
 - Pack lifecycle remains under `client.meaning.packs` (see vocabulary packs section above).
 
+## Meaning: semantic proposals (Phase 2)
+
+Agent review of the same inbox Meaning shows. Batch helpers fan out to the
+single-id PUT (no dedicated batch REST).
+
+| Concern | SDK | REST |
+| --- | --- | --- |
+| list proposals | `client.meaning.proposals.list({ disposition?, proposal_type?, … })` | `GET /semantic-layer/semantic-proposals` |
+| accept | `.accept(semantic_proposal_id, { resolution_note? })` | `PUT …/semantic-proposals/{id}` `disposition: accepted` |
+| reject | `.reject(semantic_proposal_id, { resolution_note? })` | `PUT …` `disposition: rejected` |
+| batch accept / reject | `.accept_batch` / `.reject_batch` | N× PUT |
+
+## Meaning: semantic bundles (Phase 2)
+
+| MCP operation | SDK | REST |
+| --- | --- | --- |
+| `import_semantic_bundle` | `client.meaning.bundles.import({ bundle, dry_run? })` | `POST /semantic-layer/bundles/import` |
+
+Phase 0 error contract: result always includes `skipped_count` and `errors`.
+When skips/errors exist (or HTTP 207/422 with a parseable body), the SDK sets
+`partial: true` and still returns the result instead of dropping error detail.
+MCP-only sibling: `export_semantic_bundle` (no SDK yet).
+
+## Define: domain shapes (Phase 2)
+
+Domain / org **canonical shapes** (`domain_schemas`) — distinct from
+`client.define.schemas` (data-product schema versions on `/dataproducts`).
+
+| MCP operation | SDK | REST |
+| --- | --- | --- |
+| `create_schema` | `client.define.shapes.create({ name, format, … })` | `POST /semantic-layer/schemas` |
+| `list_schemas` | `.list({ domain_id?, format?, search? })` | `GET /semantic-layer/schemas` |
+| `get_schema` (by `schema_id`) | `.get(schema_id)` | `GET /semantic-layer/schemas/{schema_id}` |
+| `apply_schema` | `.apply({ schema_id, data_product_id, schema_version_id? })` | `POST …/schemas/{schema_id}/applications` |
+| `patch_schema` (align) | `.align({ schema_id, aligned_to_concept_uri })` | `PUT …/schemas/{schema_id}` |
+
+MCP-only (no SDK yet): `update_schema`, `delete_schema`, `list_schema_versions`,
+`unapply_schema`, `list_schema_applications`, `add_schema_version`,
+`get_schema_impact`, `install_schema_pack`. Data-product PII tagging stays on
+`client.define.schemas.tag_pii_fields`.
+
 ## Review: CDLC + context mining (LOX-1244…1247)
 
 MCP `loxtep_review` CDLC / mining ops map to `client.review.cdlc` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loxtep/sdk",
-  "version": "0.9.15",
+  "version": "0.9.17",
   "description": "Loxtep SDK for Node.js — the Enterprise Context Layer: data products, workflows, projects, queues, and machine-usable context for AI",
   "author": "Loxtep <engineering@loxtep.io>",
   "homepage": "https://loxtep.io",
@@ -34,17 +34,19 @@
     "dist",
     "docs",
     "schemas",
+    "templates",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc && mkdir -p dist/lib/entity-json-schemas && cp src/lib/entity-json-schemas/ajv-loader.cjs dist/lib/entity-json-schemas/ajv-loader.cjs",
+    "build": "tsc && mkdir -p dist/lib/entity-json-schemas && cp src/lib/entity-json-schemas/ajv-loader.cjs dist/lib/entity-json-schemas/ajv-loader.cjs && cp src/cli/resolve-package-root.cjs dist/cli/resolve-package-root.cjs",
     "prepublishOnly": "npm run build",
     "test": "jest --config jest.config.cjs",
     "lint": "eslint src --ext .ts",
     "sync:entity-schemas": "node scripts/sync-entity-schemas.mjs",
     "generate:api-types": "tsx scripts/generate-api-types.ts",
     "docs": "typedoc",
-    "test:e2e:cli": "bash scripts/cli-e2e.sh"
+    "test:e2e:cli": "bash scripts/cli-e2e.sh",
+    "test:e2e:try-it": "bash scripts/try-it-onboarding-e2e.sh"
   },
   "publishConfig": {
     "access": "public",
@@ -89,6 +91,7 @@
     "ajv-formats": "^3.0.1",
     "js-yaml": "^4.3.0",
     "leo-sdk": "7.1.21",
+    "tsx": "^4.22.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
@@ -97,7 +100,6 @@
     "fast-check": "^4.8.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.9",
-    "tsx": "^4.22.0",
     "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
     "zod-to-ts": "^2.0.0"

package/templates/shopify-orders/AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md — shopify-orders
+
+This project was scaffolded from the `shopify-orders` template (Try it sample).
+
+## MCP tools
+
+```json
+{ "mcpServers": { "loxtep": { "url": "https://mcp.loxtep.io/ai/mcp/stream" } } }
+```
+
+Dev MCP host: `https://mcpdev.loxtep.io/ai/mcp/stream`.
+
+## Lifecycle
+
+```bash
+loxtep login
+loxtep attach --instance <non-prod-instance-id>
+loxtep setup
+loxtep generate
+loxtep test orders-enricher --event ./events/order-created.json
+loxtep deploy
+```
+
+`loxtep test` runs the handler locally with **live** instance I/O. Approve
+`dataProducts.write` when prompted.
+
+## SDK methods
+
+- `LoxtepClient.fromWorkspace()` — configure from `.loxtep/project.json`
+- `defineDataWorkflow({ name, triggers, handler, requireApproval })`
+- `workspace.dataProducts.*` — typed constants after `loxtep generate`
+
+## Skill scope
+
+Default skill: `.loxtep/skills/shopify-orders.yaml`

package/templates/shopify-orders/README.md

@@ -0,0 +1,50 @@
+# Shopify orders sample (`shopify-orders`)
+
+Minimal code-first Loxtep workspace used by [Try it](https://loxtep.io/try-it).
+
+## Prerequisites
+
+| Requirement | Notes |
+| --- | --- |
+| **Node.js 22+** | `node --version` |
+| **Loxtep account** | [app.loxtep.io](https://app.loxtep.io) |
+| **Auth** | `loxtep login` (writes `./.loxtep/credentials.json`) |
+| **Instance** | Non-production preferred — `loxtep instances list` then `loxtep attach` |
+| **Domain** | Org must have at least one domain (create in UI if none) |
+
+`loxtep test` executes your handler **locally with live instance I/O** (stream writes).
+It is not an offline simulator. Sample writes require terminal approval
+(`requireApproval: ['dataProducts.write']`).
+
+## Lifecycle (empty directory → deploy)
+
+```bash
+mkdir shopify-orders-demo && cd shopify-orders-demo
+npm init -y
+npm install @loxtep/sdk@^0.9.16
+npx loxtep login
+npx loxtep init --template shopify-orders
+npx loxtep attach --instance <non-prod-instance-id>
+npx loxtep setup                 # provisions orders_raw + orders_enriched (idempotent)
+npx loxtep generate
+npx loxtep test orders-enricher --event ./events/order-created.json
+# Approve dataProducts.write when prompted (y)
+npx loxtep deploy
+```
+
+Re-running `setup` is safe: existing data products are reused.
+
+## What this template scaffolds
+
+| Path | Purpose |
+| --- | --- |
+| `workflows/orders-enricher.ts` | Sample module (webhook → enrich → write) |
+| `events/order-created.json` | Fixture for `loxtep test` |
+| `AGENTS.md` / `.loxtep/skills/` | Agent + skill scope |
+| `package.json` / `tsconfig.json` | Node 22 + typed workflows |
+
+## Approval / failure behavior
+
+- Reject or timeout on a guarded write → operation skipped, **nonzero exit**
+- Handler or toolbox errors → recorded in the action trace, **nonzero exit**
+- Success → exit 0 and a trace with `handler.start` → `dataProducts.write` → `handler.complete`

package/templates/shopify-orders/events/order-created.json

@@ -0,0 +1,17 @@
+{
+  "id": "gid://shopify/Order/5678901234",
+  "name": "#1001",
+  "email": "customer@example.com",
+  "created_at": "2026-09-22T12:00:00Z",
+  "currency": "USD",
+  "total_price": "129.99",
+  "financial_status": "paid",
+  "line_items": [
+    {
+      "id": 1,
+      "title": "Sample Widget",
+      "quantity": 1,
+      "price": "129.99"
+    }
+  ]
+}

package/templates/shopify-orders/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "loxtep-shopify-orders-sample",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@loxtep/sdk": "^0.9.16"
+  }
+}

package/templates/shopify-orders/skills/shopify-orders.yaml

@@ -0,0 +1,29 @@
+# Default skill for the shopify-orders template.
+# Scoped to the sample resources provisioned by `loxtep setup`.
+name: shopify-orders
+description: Shopify orders enricher sample — orders_raw ingest and orders_enriched write target
+scope:
+  # workflows left empty until after first `loxtep deploy` of orders-enricher
+  # (generate validates skill refs against the live workspace).
+  data_products:
+    - orders_raw
+    - orders_enriched
+  connectors: []
+  workflows: []
+  domains: []
+  queues: []
+permissions:
+  data_products:
+    - read
+    - write
+  connectors:
+    - read
+  workflows:
+    - read
+    - write
+    - create
+  domains:
+    - read
+  queues:
+    - read
+    - write

package/templates/shopify-orders/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["workflows/**/*.ts", ".loxtep/generated/**/*.ts"]
+}

package/templates/shopify-orders/workflows/orders-enricher.ts

@@ -0,0 +1,31 @@
+/**
+ * Sample: enrich an inbound Shopify order and write it to `orders_enriched`.
+ *
+ * Prerequisites (see README / `loxtep setup`):
+ *   - attached non-production instance
+ *   - `orders_enriched` data product provisioned and deployed
+ *   - `loxtep generate` so `.loxtep/generated` exists
+ *
+ * `loxtep test` runs this handler locally against the attached instance
+ * (live stream I/O — not an offline simulation). `dataProducts.write` is
+ * gated by `requireApproval` so sample writes cannot silently hit the bus.
+ */
+import { defineDataWorkflow, on } from '@loxtep/sdk';
+import { workspace } from '../.loxtep/generated/index.js';
+
+export default defineDataWorkflow({
+  name: 'orders-enricher',
+  // Webhook trigger avoids depending on a friendly observe queue name.
+  // After `loxtep setup`, you can switch to on.queueEvent(workspace.queues.*)
+  // once a matching queue appears in `loxtep generate` output.
+  triggers: [on.webhook('/shopify/orders')],
+  requireApproval: ['dataProducts.write'],
+  async handler(ctx, event) {
+    const order = (event ?? {}) as Record<string, unknown>;
+    await ctx.toolbox.dataProducts.write(workspace.dataProducts.orders_enriched, {
+      ...order,
+      enriched_at: new Date().toISOString(),
+      source: 'orders-enricher',
+    });
+  },
+});