@lotics/cli 0.76.0 → 0.83.0

package/dist/client.js

@@ -143,15 +143,6 @@ export class LoticsClient {
     async listWorkspaces() {
         return this.request("GET", "/v1/workspaces");
     }
-    /**
-     * Resolve one workspace's info by id from the org's workspace list (the only
-     * API-key-accessible source carrying `is_dev`). Returns null when the
-     * workspace isn't visible to these credentials.
-     */
-    async getWorkspaceInfo(id) {
-        const workspaces = await this.listWorkspaces();
-        return workspaces.find((w) => w.id === id) ?? null;
-    }
     async createWorkspace(body) {
         return this.request("POST", "/v1/workspaces", body);
     }
@@ -204,16 +195,56 @@ export class LoticsClient {
         return this.request("POST", "/v1/apps", body);
     }
     /**
-     * Install an app package version into the current workspace — scaffolds the
-     * data model, deploys the package bundle, materializes its
-     * queries/workflows/agents, and pins the installation. Returns the resulting
-     * installation app. `version` omitted installs the latest published version.
+     * Install a package version into the current workspace — ONE endpoint,
+     * kind-branched into a discriminated response (`kind`). An `app` package
+     * scaffolds the data model / deploys / materializes and returns the installation
+     * app (+ advisory knowledge warnings); a `content` package installs only its
+     * doc corpus and returns the installation row. `bind_to` (content only)
+     * resolves a name collision by adopting an existing same-named doc as
+     * package-managed. `version` omitted installs the latest published version.
+     */
+    async installPackage(package_id, body) {
+        return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/installations`, body);
+    }
+    /**
+     * Uninstall a standalone content package — delete the installation row. By
+     * default the package-bound docs are ARCHIVED; `keep_content` retains them as
+     * ordinary workspace docs. Admin-only. Backs `lotics uninstall`.
+     */
+    async uninstallContentPackage(installation_id, opts = {}) {
+        const qs = opts.keep_content ? "?keep_content=true" : "";
+        return this.request("DELETE", `/v1/content-installations/${encodeURIComponent(installation_id)}${qs}`);
+    }
+    /**
+     * Preview upgrading a standalone content installation — the knowledge namespace's
+     * per-alias `entries` (added/changed/removed/drifted + a `modified` flag) plus the
+     * consent-requiring `templates` (a template the target changed whose live content
+     * was locally edited; a clean one auto-updates and is absent). No writes.
+     * Admin-only.
+     */
+    async previewContentInstallationUpgrade(installation_id, opts = {}) {
+        const qs = opts.version !== undefined ? `?version=${opts.version}` : "";
+        return this.request("GET", `/v1/content-installations/${encodeURIComponent(installation_id)}/upgrade${qs}`);
+    }
+    /**
+     * Apply a standalone content upgrade — propagate the target version's content per
+     * the resolutions (`knowledge`: a modified change/removal or drift needs consent;
+     * `templates`: a locally-edited changed template takes revert|keep), then advance
+     * the pin + binding. Returns the updated installation row. Admin-only.
      */
-    async installAppPackage(package_id, body) {
-        return this.request("POST", `/v1/app-packages/${encodeURIComponent(package_id)}/installations`, body);
+    async applyContentInstallationUpgrade(installation_id, body) {
+        return this.request("POST", `/v1/content-installations/${encodeURIComponent(installation_id)}/upgrade`, body);
     }
     /**
-     * Uninstall a package installation (backs `lotics package uninstall`). Does
+     * List a workspace's package-managed knowledge installations, each folded with
+     * registry status (name, kind, official badge, latest version, update-available).
+     * Member-accessible (workspace-scoped); backs the settings "Managed by" badge.
+     */
+    async listContentInstallations(workspace_id) {
+        return this.request("GET", `/v1/workspaces/${encodeURIComponent(workspace_id)}/content-installations`);
+    }
+    /**
+     * Uninstall a package installation (backs `lotics uninstall`). Does
      * everything DELETE does plus archives the installation's lifecycle
      * artifacts; with `archive_tables` it also archives the scaffolded entity
      * tables — refused server-side unless this installation created them
@@ -231,13 +262,14 @@ export class LoticsClient {
         return this.request("PATCH", `/v1/apps/${encodeURIComponent(app_id)}/package-config`, body);
     }
     /**
-     * Retire (or `undo` un-retire) a registry package (backs `lotics package
-     * retire`). Retiring refuses NEW installs and hides the package from
-     * non-owning orgs; existing installations keep working and may still upgrade.
-     * Owner-org admin-only.
+     * Retire (or `undo` un-retire) a registry package (backs `lotics app
+     * unpublish` — the endpoint/audit action keep the `retire` name to avoid API
+     * churn). Retiring refuses NEW installs and hides the package from non-owning
+     * orgs; existing installations keep working and may still upgrade. Owner-org
+     * admin-only.
      */
-    async retireAppPackage(package_id, body) {
-        return this.request("POST", `/v1/app-packages/${encodeURIComponent(package_id)}/retire`, body);
+    async retirePackage(package_id, body) {
+        return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/retire`, body);
     }
     /**
      * Eject an installation from its package — re-deploy the pinned version's
@@ -246,40 +278,15 @@ export class LoticsClient {
      * app becomes a normal bespoke app and can no longer be upgraded. Returns the
      * resulting app.
      */
-    async ejectAppPackage(app_id) {
+    async ejectPackage(app_id) {
         return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/eject`);
     }
-    /**
-     * Extract a DRAFT app package from an existing bespoke app — the promotion
-     * read (docs/app_packages.md § Promotion). Pure: nothing is written. Returns
-     * the alias-keyed draft `contract` (opaque to the CLI — the server is the
-     * validating authority), the origin workspace's `binding` (which doubles as
-     * the adopt binding), a findings `report` (any `error` ⇒ not publishable
-     * as-is), and the file-backed `template_files` the CLI must stage into the
-     * project at their `bytes_ref` paths. Backs `lotics package extract`.
-     * Admin-only.
-     */
-    async extractAppPackage(app_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-extract`);
-    }
-    /**
-     * Adopt a published package onto an EXISTING (bespoke or ejected) app — the
-     * final promotion step. The workspace already holds the concrete objects, so
-     * nothing is scaffolded or rewritten: the server verifies the `binding` is
-     * complete, live, and FAITHFUL to the version's contract, then writes only the
-     * installation pin (the app becomes installation #1, upgradeable again). A
-     * ConflictError names the aliases that diverge. `version` omitted adopts the
-     * latest. Backs `lotics package adopt`. Admin-only.
-     */
-    async adoptAppPackage(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-adopt`, body);
-    }
     /**
      * Fleet upgrade — bring every installation of a package across the CALLER'S
      * org to the target version (latest when omitted) in one call. Hands-off
      * applies only where the preview is clean; installations with breaking/
      * drift/modified-core findings are skipped and reported for the normal
-     * per-installation consent flow. Backs `lotics package fleet-upgrade`.
+     * per-installation consent flow. Backs `lotics upgrade <package_id>` (fleet).
      * Admin-only; org-scoped (no workspace header needed).
      */
     /**
@@ -287,57 +294,26 @@ export class LoticsClient {
      * adopts targeting it; pinned installations keep running. Owner-org
      * admin-only. Backs `lotics package yank`.
      */
-    async yankAppPackageVersion(package_id, version, yanked) {
-        return this.request("POST", `/v1/app-packages/${encodeURIComponent(package_id)}/versions/${version}/yank`, { yanked });
+    async yankPackageVersion(package_id, version, yanked) {
+        return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/versions/${version}/yank`, { yanked });
     }
-    async fleetUpgradeAppPackage(package_id, body) {
-        return this.request("POST", `/v1/app-packages/${encodeURIComponent(package_id)}/fleet-upgrade`, body);
-    }
-    // --- App packages (registry authoring + dev harness) ---
-    /**
-     * Create a registry app package — the Lotics-owned, workspace-agnostic
-     * blueprint. `lotics package publish` calls this on first publish (when the
-     * local manifest has no `package_id`), then publishes version 1 against the
-     * returned id. Admin-only.
-     */
-    async createAppPackage(body) {
-        return this.request("POST", "/v1/app-packages", body);
+    async fleetUpgradePackage(package_id, body) {
+        return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/fleet-upgrade`, body);
     }
+    // --- Packages (registry reads + installations) ---
+    // Authoring is server-side: apps via `POST /v1/apps/{id}/package-publish|release`,
+    // content packages via the `publish_content`/`release_content` tools. There is no
+    // client-side create-package / upload-bundle path.
     /**
-     * Fetch a registry app package's metadata (incl. `latest_version` and the
-     * Lotics-backed `is_official` trust badge). Admin-only; cross-tenant by id.
+     * Fetch a registry app package's metadata (incl. `kind`, `latest_version` and
+     * the Lotics-backed `is_official` trust badge). Admin-only; cross-tenant by id.
      */
-    async getAppPackage(package_id) {
-        return this.request("GET", `/v1/app-packages/${encodeURIComponent(package_id)}`);
+    async getPackage(package_id) {
+        return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}`);
     }
     /** Version history newest-first (no contract payloads) — backs `lotics package show`. Admin-only. */
-    async listAppPackageVersions(package_id) {
-        return this.request("GET", `/v1/app-packages/${encodeURIComponent(package_id)}/versions`);
-    }
-    /**
-     * Publish a new immutable package version — multipart upload of the alias-keyed
-     * contract (JSON) + the prebuilt code bundle (a gzipped tarball carrying
-     * `source.tar.gz` + `dist.tar.gz` members). The server validates the contract +
-     * bundle, then allocates the next monotonic version. The `contract` is opaque
-     * JSON to the transport (the server is the validating authority). Admin-only.
-     */
-    async publishAppPackageVersion(package_id, args) {
-        const formData = new FormData();
-        formData.append("contract", JSON.stringify(args.contract));
-        formData.append("bundle", new Blob([new Uint8Array(args.bundle)], { type: "application/gzip" }), "bundle.tar.gz");
-        if (args.changelog)
-            formData.append("changelog", args.changelog);
-        if (args.channel)
-            formData.append("channel", args.channel);
-        const url = `${this.baseUrl}/v1/app-packages/${encodeURIComponent(package_id)}/versions`;
-        const response = await fetch(url, {
-            method: "POST",
-            headers: this.buildHeaders(), // no Content-Type — fetch sets the multipart boundary
-            body: formData,
-        });
-        if (!response.ok)
-            await this.throwResponseError(response);
-        return response.json();
+    async listPackageVersions(package_id) {
+        return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}/versions`);
     }
     /**
      * Upgrade a package installation to a newer published version — extends the
@@ -346,7 +322,7 @@ export class LoticsClient {
      * package artifacts, and bumps the pin. `version` omitted upgrades to the
      * latest. Returns the resulting app. Admin-only.
      */
-    async upgradeAppPackage(app_id, body) {
+    async upgradePackage(app_id, body) {
         return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-upgrade`, body);
     }
     /**
@@ -354,18 +330,10 @@ export class LoticsClient {
      * breaking contract changes, the binding drift report, and the modified-core
      * report — with no writes. Admin-only.
      */
-    async previewAppPackageUpgrade(app_id, opts = {}) {
+    async previewPackageUpgrade(app_id, opts = {}) {
         const query = opts.version !== undefined ? `?version=${opts.version}` : "";
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-upgrade${query}`);
     }
-    /**
-     * Re-bind a package role to a different workspace group (the current group
-     * still exists). Re-materializes at the pinned version; refuses over
-     * modified-core findings. Admin-only.
-     */
-    async rebindAppPackageRole(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-rebind-role`, body);
-    }
     /**
      * Workspace-wide dangling-reference sweep — active app/workflow artifacts
      * whose prefixed schema ids no longer resolve. Backs
@@ -379,17 +347,60 @@ export class LoticsClient {
      * binding drift, and locally modified core artifacts. Read-only; backs
      * `lotics package doctor`. Admin-only.
      */
-    async getAppPackageHealth(app_id) {
+    async getPackageHealth(app_id) {
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-health`);
     }
     /**
-     * Reset a package installation in a DEV workspace — drop the package-owned
-     * scaffolded tables and re-scaffold clean. Hard-gated server-side to dev
-     * workspaces (a non-dev workspace is refused). Returns the resulting app.
-     * Admin-only.
+     * Preview a release — the dry run behind `lotics app release`. Runs the
+     * binding-aware extract of the origin (aliases stable through the app's current
+     * binding) and reports the next version number, the new + changed aliases, and
+     * any extract findings (an `error` blocks the apply). No writes. Admin,
+     * owning-org only.
+     */
+    async previewPackageRelease(app_id) {
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release`);
+    }
+    /**
+     * Release — snapshot the origin app into the next registry version. The server
+     * binding-aware-extracts it, repackages its deployed source + dist as the
+     * bundle, publishes the next `release`-channel version with the changelog, and
+     * re-pins the origin. Error findings from extract surface as a 409. Admin,
+     * owning-org only. Backs `lotics app release --yes`.
+     */
+    async releasePackage(app_id, body) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-release`, body);
+    }
+    /**
+     * Dry-run preview of a first-release — the `GET` behind `lotics app publish`
+     * (no `--yes`), the publish-side analogue of `previewPackageRelease`. The
+     * server runs the same fresh-alias extract + `src/` scan the apply runs
+     * (through any `renames`) and returns the package name it would mint, the
+     * auto-minted RENAMABLE aliases (the exact `--rename` keys), and the extract
+     * findings (an `error` blocks the apply). No writes. Admin-only.
+     */
+    async previewPublishAppPackage(app_id, opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
+            params.set("knowledge", JSON.stringify(opts.knowledge));
+        }
+        if (opts.renames !== undefined && opts.renames.length > 0) {
+            params.set("renames", JSON.stringify(opts.renames));
+        }
+        const query = params.toString();
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-publish${query ? `?${query}` : ""}`);
+    }
+    /**
+     * First-release apply — mint a package from a BESPOKE app and publish v1 in one
+     * call (the `POST` behind `lotics app publish --yes`). The server extracts an
+     * alias-keyed contract from the app (fresh aliases; `renames` fixes them before
+     * v1 freezes), creates the registry package (name/description from the app),
+     * publishes v1 from the app's deployed source + dist, and pins the origin as
+     * installation #1. Error findings from extract surface as a 409. An
+     * already-linked app must use `releasePackage` instead. Admin-only. Backs
+     * `lotics app publish <app_id>`.
      */
-    async resetAppPackage(app_id) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-reset`);
+    async publishAppAsPackage(app_id, body) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-publish`, body);
     }
     /**
      * Resolve the display name + fields (incl. select options) of the given tables

package/dist/generate_package_fields.d.ts

@@ -1,48 +1,49 @@
 /**
- * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PACKAGE project from
- * its `contract.json`.
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PUBLISHED / linked app
+ * (a package installation — its own published origin, or an install of another
+ * org's package) from that installation's LIVE binding.
  *
- * The bespoke twin (`generate_app_fields.ts`) bakes this workspace's concrete
- * `fld_…`/`opt_…` ids at authoring time — correct when source and workspace
- * co-live, fundamentally wrong for a package (one bundle, many workspaces,
- * different ids in each). A package project instead resolves the SAME `F` /
- * `OPT` surface at MODULE LOAD from the installation's binding via the SDK's
- * `getAppBinding()` (the `binding` RPC op), using top-level await — the ESM
- * graph waits for the binding before any importer evaluates, so
- * `F.TASKS.title` is a plain string everywhere, including module-top-level
- * constants. Extracted bespoke sources therefore compile unchanged: same
- * import path, same shapes, same alias naming (contract aliases derive from
- * the same display names the bespoke codegen slugifies).
+ * The bespoke twin (`generate_app_fields.ts`) bakes THIS workspace's concrete
+ * `fld_…`/`opt_…` ids at codegen time — correct when source and workspace
+ * co-live, fundamentally wrong for a linked app (the source is portable and
+ * installs into many workspaces, each with different ids). A linked app instead
+ * resolves the SAME `F` / `OPT` / `ROLE` surface at MODULE LOAD from the
+ * installation's binding via the SDK's `getAppBinding()` (the `binding` RPC op),
+ * using top-level await — the ESM graph waits for the binding before any
+ * importer evaluates, so `F.TASKS.title` is a plain string everywhere, including
+ * module-top-level constants. A published origin's source is portable by
+ * construction: same import path, same `F`/`OPT` shapes the bespoke codegen
+ * emitted (contract aliases derive from the same display names it slugifies), so
+ * the deployed source compiles unchanged, resolved per-install.
  *
- * A missing alias fails LOUD at boot (the binding is adopt/install-verified
- * complete, so a miss means the generated file is stale relative to the
- * installed contract version) — never a silent undefined key in a write.
+ * The generator sources the alias SET from the app's LIVE binding (the `binding`
+ * RPC / `appBinding` client method), NOT a contract file: every bound field
+ * (`entity.field`), option (`entity.field:opt`), and role becomes an `F` / `OPT`
+ * / `ROLE` entry keyed by its stable alias.
+ *
+ * A missing alias fails LOUD at boot (the binding is install-verified complete,
+ * so a miss means the generated file is stale relative to the installed contract
+ * version) — never a silent undefined key in a write.
  *
  * Requires the app build to target es2022+ (the starter's `build.target`) —
  * top-level await does not exist below it.
  */
-/** The subset of a contract this generator reads (structural, not zod-validated —
- *  publish is the validating boundary; codegen must work on drafts too). */
-export interface PackageContractShape {
-    entities?: Array<{
-        alias: string;
-        fields?: Array<{
-            alias: string;
-            options?: Array<{
-                alias: string;
-            }>;
-        }>;
-    }>;
-    roles?: Array<{
-        alias: string;
-    }>;
+/**
+ * A materialized app installation's binding — the exact shape the `binding` RPC
+ * / `client.appBinding()` returns (a subset of the full package binding: only
+ * the maps the client-side `F`/`OPT`/`ROLE` surface resolves through). Keys are
+ * fully-qualified contract aliases: `fields` keyed `entity.field`, `options`
+ * keyed `entity.field:opt`, `roles` keyed by role alias.
+ */
+export interface AppFieldsBinding {
+    fields: Record<string, string>;
+    options: Record<string, string>;
+    roles: Record<string, string>;
 }
 /**
- * Generate the full package `.lotics/app_fields.ts` source. Valid contract
- * aliases are slug-grammar (`^[a-z][a-z0-9_]*$`) and emit as bare identifiers
- * — but this also runs on unvalidated DRAFTS (dev/sync pre-publish), so every
- * key goes through `propKey`, which quotes anything that isn't a valid
- * identifier instead of emitting broken TypeScript into a "DO NOT EDIT" file.
- * Pure; same contract → same bytes.
+ * Generate the full binding-resolved `.lotics/app_fields.ts` source from an
+ * installation's live binding. Pure — same binding → same bytes. Idempotent.
+ * An empty binding yields valid, empty `F`/`OPT`/`ROLE` maps so the file always
+ * compiles and imports resolve.
  */
-export declare function generatePackageAppFields(contract: PackageContractShape): string;
+export declare function generatePackageAppFields(binding: AppFieldsBinding): string;

package/dist/generate_package_fields.js

@@ -1,34 +1,41 @@
 /**
- * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PACKAGE project from
- * its `contract.json`.
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PUBLISHED / linked app
+ * (a package installation — its own published origin, or an install of another
+ * org's package) from that installation's LIVE binding.
  *
- * The bespoke twin (`generate_app_fields.ts`) bakes this workspace's concrete
- * `fld_…`/`opt_…` ids at authoring time — correct when source and workspace
- * co-live, fundamentally wrong for a package (one bundle, many workspaces,
- * different ids in each). A package project instead resolves the SAME `F` /
- * `OPT` surface at MODULE LOAD from the installation's binding via the SDK's
- * `getAppBinding()` (the `binding` RPC op), using top-level await — the ESM
- * graph waits for the binding before any importer evaluates, so
- * `F.TASKS.title` is a plain string everywhere, including module-top-level
- * constants. Extracted bespoke sources therefore compile unchanged: same
- * import path, same shapes, same alias naming (contract aliases derive from
- * the same display names the bespoke codegen slugifies).
+ * The bespoke twin (`generate_app_fields.ts`) bakes THIS workspace's concrete
+ * `fld_…`/`opt_…` ids at codegen time — correct when source and workspace
+ * co-live, fundamentally wrong for a linked app (the source is portable and
+ * installs into many workspaces, each with different ids). A linked app instead
+ * resolves the SAME `F` / `OPT` / `ROLE` surface at MODULE LOAD from the
+ * installation's binding via the SDK's `getAppBinding()` (the `binding` RPC op),
+ * using top-level await — the ESM graph waits for the binding before any
+ * importer evaluates, so `F.TASKS.title` is a plain string everywhere, including
+ * module-top-level constants. A published origin's source is portable by
+ * construction: same import path, same `F`/`OPT` shapes the bespoke codegen
+ * emitted (contract aliases derive from the same display names it slugifies), so
+ * the deployed source compiles unchanged, resolved per-install.
  *
- * A missing alias fails LOUD at boot (the binding is adopt/install-verified
- * complete, so a miss means the generated file is stale relative to the
- * installed contract version) — never a silent undefined key in a write.
+ * The generator sources the alias SET from the app's LIVE binding (the `binding`
+ * RPC / `appBinding` client method), NOT a contract file: every bound field
+ * (`entity.field`), option (`entity.field:opt`), and role becomes an `F` / `OPT`
+ * / `ROLE` entry keyed by its stable alias.
+ *
+ * A missing alias fails LOUD at boot (the binding is install-verified complete,
+ * so a miss means the generated file is stale relative to the installed contract
+ * version) — never a silent undefined key in a write.
  *
  * Requires the app build to target es2022+ (the starter's `build.target`) —
  * top-level await does not exist below it.
  */
 import { propKey } from "./generate_app_fields.js";
-const HEADER = `// Auto-generated by 'lotics package new/extract/dev/sync' from contract.json.
-// DO NOT EDIT — regenerated whenever the contract changes.
+const HEADER = `// Auto-generated by 'lotics app codegen' (linked/published app; also app pull/dev/deploy).
+// DO NOT EDIT — regenerated from the installation's live binding.
 //
-// Package apps resolve F/OPT/ROLE at MODULE LOAD from the installation's
-// binding (contract alias → THIS workspace's concrete id) via the SDK's
-// \`binding\` RPC. Top-level await: the module graph waits for the binding
-// before any importer evaluates, so every entry is a plain string.
+// A package installation resolves F/OPT/ROLE at MODULE LOAD from its binding
+// (contract alias → THIS workspace's concrete id) via the SDK's \`binding\` RPC.
+// Top-level await: the module graph waits for the binding before any importer
+// evaluates, so every entry is a plain string.
 import { getAppBinding } from "@lotics/app-sdk";
 
 const binding = await getAppBinding();
@@ -45,54 +52,100 @@ function bound(map: Record<string, string>, key: string, kind: string): string {
 }
 `;
 /**
- * Generate the full package `.lotics/app_fields.ts` source. Valid contract
- * aliases are slug-grammar (`^[a-z][a-z0-9_]*$`) and emit as bare identifiers
- * — but this also runs on unvalidated DRAFTS (dev/sync pre-publish), so every
- * key goes through `propKey`, which quotes anything that isn't a valid
- * identifier instead of emitting broken TypeScript into a "DO NOT EDIT" file.
- * Pure; same contract → same bytes.
+ * Reconstruct the entity → field → option nesting (plus role list) from the flat
+ * binding maps. Entity/field/option aliases are slug-grammar (`[a-z][a-z0-9_]*`,
+ * no `.` or `:`), so a field key splits on its single `.` and an option key on
+ * its single `:`. First-seen order is preserved (the binding is written in
+ * contract order), so the output is deterministic for a given binding. An option
+ * whose owning field is absent from `fields` is skipped defensively — the binding
+ * is the authority, and a select field is always present among the fields.
  */
-export function generatePackageAppFields(contract) {
-    const entities = contract.entities ?? [];
-    const roles = contract.roles ?? [];
-    const fieldBlocks = [];
-    for (const entity of entities) {
-        const lines = (entity.fields ?? []).map((field) => `    ${propKey(field.alias)}: bound(binding.fields, ${JSON.stringify(`${entity.alias}.${field.alias}`)}, "field"),`);
-        if (lines.length === 0)
+function parseBinding(binding) {
+    const entities = [];
+    const entityByAlias = new Map();
+    const fieldByKey = new Map();
+    for (const key of Object.keys(binding.fields)) {
+        const dot = key.indexOf(".");
+        if (dot <= 0 || dot >= key.length - 1)
+            continue;
+        const entityAlias = key.slice(0, dot);
+        const fieldAlias = key.slice(dot + 1);
+        let entity = entityByAlias.get(entityAlias);
+        if (entity === undefined) {
+            entity = { alias: entityAlias, fields: [] };
+            entityByAlias.set(entityAlias, entity);
+            entities.push(entity);
+        }
+        const field = { alias: fieldAlias, key, options: [] };
+        entity.fields.push(field);
+        fieldByKey.set(key, field);
+    }
+    for (const key of Object.keys(binding.options)) {
+        const colon = key.indexOf(":");
+        if (colon <= 0 || colon >= key.length - 1)
+            continue;
+        const fieldKey = key.slice(0, colon);
+        const optionAlias = key.slice(colon + 1);
+        const field = fieldByKey.get(fieldKey);
+        if (field === undefined)
             continue;
-        fieldBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${lines.join("\n")}\n  },`);
+        field.options.push({ alias: optionAlias, key });
     }
-    const optionBlocks = [];
+    return { entities, roles: Object.keys(binding.roles) };
+}
+/** Emit the `F` map: `{ ENTITY: { field: bound(binding.fields, "entity.field", "field") } }`. */
+function emitFieldMap(entities) {
+    if (entities.length === 0)
+        return `export const F = {} as const;`;
+    const blocks = entities.map((entity) => {
+        const lines = entity.fields.map((field) => `    ${propKey(field.alias)}: bound(binding.fields, ${JSON.stringify(field.key)}, "field"),`);
+        return `  ${propKey(entity.alias.toUpperCase())}: {\n${lines.join("\n")}\n  },`;
+    });
+    return `export const F = {\n${blocks.join("\n")}\n} as const;`;
+}
+/**
+ * Emit the `OPT` map: `{ ENTITY: { field: { opt: bound(binding.options, …) } } }`.
+ * Only fields carrying options appear (an option-less field/entity is omitted).
+ */
+function emitOptionMap(entities) {
+    const entityBlocks = [];
     for (const entity of entities) {
-        const perField = [];
-        for (const field of entity.fields ?? []) {
-            const options = field.options ?? [];
-            if (options.length === 0)
+        const fieldBlocks = [];
+        for (const field of entity.fields) {
+            if (field.options.length === 0)
                 continue;
-            const lines = options.map((option) => `      ${propKey(option.alias)}: bound(binding.options, ${JSON.stringify(`${entity.alias}.${field.alias}:${option.alias}`)}, "option"),`);
-            perField.push(`    ${propKey(field.alias)}: {\n${lines.join("\n")}\n    },`);
-        }
-        if (perField.length > 0) {
-            optionBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${perField.join("\n")}\n  },`);
+            const lines = field.options.map((option) => `      ${propKey(option.alias)}: bound(binding.options, ${JSON.stringify(option.key)}, "option"),`);
+            fieldBlocks.push(`    ${propKey(field.alias)}: {\n${lines.join("\n")}\n    },`);
         }
+        if (fieldBlocks.length === 0)
+            continue;
+        entityBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${fieldBlocks.join("\n")}\n  },`);
     }
-    const fMap = fieldBlocks.length > 0
-        ? `export const F = {\n${fieldBlocks.join("\n")}\n} as const;`
-        : `export const F = {} as const;`;
-    const optMap = optionBlocks.length > 0
-        ? `export const OPT = {\n${optionBlocks.join("\n")}\n} as const;`
-        : `export const OPT = {} as const;`;
-    const roleMap = roles.length > 0
-        ? `export const ROLE = {\n${roles
-            .map((role) => `  ${propKey(role.alias)}: bound(binding.roles, ${JSON.stringify(role.alias)}, "role"),`)
-            .join("\n")}\n} as const;`
-        : `export const ROLE = {} as const;`;
+    if (entityBlocks.length === 0)
+        return `export const OPT = {} as const;`;
+    return `export const OPT = {\n${entityBlocks.join("\n")}\n} as const;`;
+}
+/** Emit the `ROLE` map: `{ role: bound(binding.roles, "role", "role") }`. */
+function emitRoleMap(roles) {
+    if (roles.length === 0)
+        return `export const ROLE = {} as const;`;
+    const lines = roles.map((role) => `  ${propKey(role)}: bound(binding.roles, ${JSON.stringify(role)}, "role"),`);
+    return `export const ROLE = {\n${lines.join("\n")}\n} as const;`;
+}
+/**
+ * Generate the full binding-resolved `.lotics/app_fields.ts` source from an
+ * installation's live binding. Pure — same binding → same bytes. Idempotent.
+ * An empty binding yields valid, empty `F`/`OPT`/`ROLE` maps so the file always
+ * compiles and imports resolve.
+ */
+export function generatePackageAppFields(binding) {
+    const { entities, roles } = parseBinding(binding);
     return `${HEADER}
-${fMap}
+${emitFieldMap(entities)}
 
-${optMap}
+${emitOptionMap(entities)}
 
-${roleMap}
+${emitRoleMap(roles)}
 
 /** Field-id alias map: \`F[<ENTITY>][<field>]\` is this installation's \`fld_…\` id. */
 export type AppFields = typeof F;