@owlmeans/viable-common 0.0.4

package/README.md

@@ -0,0 +1,68 @@
+# @owlmeans/viable-common
+
+Runtime-free contracts of the OwlMeans Viable platform.
+
+Viable turns a description into a running full-stack application. Four runtimes have to agree
+about every name involved — the manager API, the agent, the publisher that runs inside a project
+slot, and the connector SDK on a developer's machine — so each of those names is declared here
+once and imported by all of them. There is no runtime in this package: no `@langchain/*`, no
+filesystem, no inference SDK. It is safe to import from a browser bundle.
+
+## What is in it
+
+| Subpath | Contents |
+|---|---|
+| `.` | The shapes a generated project is described by: user stories and entities, the design and scaffold plans, UX/UI specs, the `docs/` metadata paths, the four user areas, the model roles and personas, moderation categories, slot metadata |
+| `@owlmeans/viable-common/slot` | The slot command vocabulary — file, shell and git commands, the sub-project roles, the target's ports and process markers |
+| `@owlmeans/viable-common/connect` | The connector protocol: sessions, operations, model tasks, questions, jobs, capabilities, the error family, and `connectEntrypoints()` — the one declaration both the platform and the SDK elevate |
+| `@owlmeans/viable-common/convert` | Converting an application that already exists: the stages and their transitions, the origin and stack taxonomy, the census classifiers, and the `docs/conversion/` layout |
+| `@owlmeans/viable-common/integrity` | The target-shape manifest — what a slot is allowed to install, build and run — per target layout |
+
+## Installation
+
+```bash
+bun add @owlmeans/viable-common@^0.0.4
+```
+
+## Rules worth knowing before you change something
+
+**A schema is written for the reader that will refuse it.** Model-answer schemas are annotated
+`JSONSchemaType<T>` so a drift from the type is caught where it is written; record schemas are
+hand-written and cast, because they are re-applied as a Mongo `$jsonSchema`, which admits no
+`Record<>` maps, no `integer` and no date objects.
+
+**`nullable: true` always carries its `type`, and a nullable `enum` lists `null` among its
+values.** Ajv checks `nullable` and `enum` independently, so the pair written apart admits `null`
+by type and then refuses it by enum — the field can only ever be omitted, never sent empty. A
+provider's structured output writes an unset optional as `null`, and a wire body where `null`
+means "inherit" has no other spelling. `tests/convert.spec.ts` walks every exported schema for
+both faults, and for draft-04 tuple `items`.
+
+**A field that crosses a version skew carries no `enum`.** A connector is installed with
+`npx -y @owlmeans/viable-mcp` and talks to a separately deployed platform, so an executor kind it
+sends must remain an unused capability on an older platform rather than a refused session.
+
+**A ceiling exists once.** The inquiry answer cap here equals `DEFAULT_INQUIRY_ANSWER_CHARS` in
+`@owlmeans/llm-common` and must stay equal; two ceilings mean the larger one truncates silently
+at the smaller.
+
+## Related
+
+- `@owlmeans/viable-sdk` — the connector SDK written against these contracts
+- `@owlmeans/viable-mcp` — the npx MCP server built on that SDK
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.13
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/viable-common",
+  "version": "0.0.4",
+  "generatedAt": "2026-09-10T18:54:42.505Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "viable-common",
+      "category": "package-specific",
+      "file": "skills/viable-common/SKILL.md",
+      "canonicalPath": ".agents/skills/viable-common/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/viable-common/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: viable-common
+description: How to use @owlmeans/viable-common — the runtime-free contract package of the OwlMeans Viable platform. Covers the slot command vocabulary and target layouts, the target-shape integrity manifest, the connector protocol and its entrypoints, the conversion vocabulary, the analysis/design/metadata shapes a generated project is described by, the schema conventions every model answer and stored record here is written to (nullable with its type, a nullable enum carrying null, no Record maps in a record schema), and the version-skew rule a name on the wire obeys. Auto-invoked when importing a slot command, a connector or conversion type, a target-integrity helper, or any *Schema this package exports.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/viable-common
+
+**Layer:** Cross-cutting domain (contracts only)
+**Install:** `"@owlmeans/viable-common": "^0.0.4"` in `dependencies`
+**Subpaths:** `.` · `./slot` · `./connect` · `./convert` · `./integrity`
+**Runtime-free:** no `@langchain/*`, no filesystem, no Ajv at run time (a devDependency, for the
+tests that compile the schemas). It depends on `@owlmeans/entrypoint`, `@owlmeans/route`,
+`@owlmeans/error`, `@owlmeans/agent-common` and `@owlmeans/llm-common` and on nothing else.
+
+Every name the OwlMeans Viable platform puts on a wire, on a volume or in a prompt is declared
+here once, and the four runtimes that must agree about it — the manager API, the agent, the
+publisher/production runtime, and the connector SDK on somebody's laptop — all read the same
+declaration. A vocabulary copied instead of imported is how one tree gets two totals, one
+refusal two spellings, and one ceiling two values.
+
+## Key Exports
+
+| Subpath | What it declares |
+|---|---|
+| `.` (barrel) | `SlotMetadata` and the three metadata vocabularies (`metadataConfigs`, `metadataLists`, `metadataSecrets`); `ProjectArea` / `AREA_PATHS` / `AREA_ACCESS` / `AREA_TIER`; `ModelRole` and the viable `ExecutionState`; `ViableSkill` / `ViablePersona` / `VIABLE_SKILLS`; the BA, dev, UX, design and scaffold shapes and their schemas; `ModerationCategory` / `ModerationSubject` / `decideModeration`; the `docs/` metadata paths; `PreviewEventType` |
+| `./slot` | `SlotCommandType` and the `SlotFileCommand` / `SlotShellCommand` / `SlotGitCommand` sets, `SubProject`, `WorkloadKind`, the target ports and process markers, `slotOrigin` / `targetRedirectUrisForOrigin` |
+| `./connect` | `ConnectTarget`, `ConnectLlm`, `ConnectHarness`, `ConnectExecutor`, `ConnectOpKind`, `ConnectJobKind`/`Status`/`Block`, `ModelTier` + `tierOfRole`/`clampTier`, `ModelTask*`, `InquiryPayload` + `ConnectInquiryKind`, the session/job/status views, the `Connect*` error family, `connectEntrypoints(opts)` and every `*Schema` behind them |
+| `./convert` | `ConversionStage`/`Status`/`Decision` and the `stageAfter`/`decisionFor`/`canEnter` transitions, `OriginKind`/`Shape`/`State`, `StackId` + `STACK_FAMILY`, `ArchitectureCase`, `ConvertibilityVerdict`/`Reason`, the census classifiers (`fileClassOf`, `sizeClassOf`, `entropyClassOf`, `binaryByExtension`), the `docs/conversion/` paths, `CONVERTED_ORIGIN_DIR`, `SOURCE_LIST_EXCLUSIONS`, `CENSUS_SKIP_DIRS`, `RELOCATE_ALWAYS_KEEP`, and the model-answer schemas the conversion asks with |
+| `./integrity` | `TargetLayout` + `TARGET_LAYOUTS`, `detectTargetLayout`, `verifyTargetShape`, `TARGET_INTEGRITY_FILES`, `TARGET_PROTECTED_FILES`, `isLegacyLayout`, `targetPackageName` |
+
+## A schema here is written for the reader that will refuse it
+
+Two populations live side by side and are written differently on purpose. Getting the population
+wrong is not a style error — each reader refuses a different thing, and one of them refuses at
+boot rather than at the call.
+
+**Model-answer schemas** are the shape a model's single JSON object must take. Annotate them
+`JSONSchemaType<T>` — checked, not cast — because the answer is parsed straight back into that
+type, and a schema that drifted fails at run time with a message about a document rather than
+about a field.
+
+**Record-element schemas** describe what the platform stores and puts on the wire. They are
+hand-written and cast, because they are re-applied as a Mongo `$jsonSchema`, which is stricter
+than Ajv: no `Record<>` maps (an open key space cannot be validated), no `integer` (a stored
+number is a double), dates as ISO strings rather than objects.
+
+Three rules hold for both, and `tests/convert.spec.ts` walks **the package barrel** for each —
+not the conversion barrel, although the file is the conversion's, because none of the three
+faults is particular to a conversion and a walk over one directory lets the same shape through
+in a design, a slot or a connector schema:
+
+- **`nullable: true` always carries its `type`.** Ajv refuses `nullable` on its own, and a schema
+  that fails to compile takes down whatever compiled it — the route registration, the collection
+  validator — instead of the one call that would have carried the value.
+- **A nullable ENUM lists `null` among its values**: `enum: [...Object.values(X), null]`.
+  `nullable` and `enum` are separate keywords checked independently, so the pair written apart
+  widens the type check to admit `null` and then refuses that very value by enum — the field can
+  only ever be OMITTED, never sent empty. Nothing fails at compile time and nothing fails for a
+  caller that leaves the key out, which is why it survives review; it surfaces as the one caller
+  that spells absence as `null`. Both callers exist here: a provider's structured output writes an
+  unset optional as `null` (an intake stack call was retried three times and discarded as
+  `llm:retry-exceeded`), and a wire body where `null` MEANS something — `llmMode`, "inherit the
+  profile's setting" — has no other spelling at all.
+- **`items` is never an array.** A draft-04 tuple is refused wherever the schema reaches a
+  provider or a collection validator.
+
+**A field that crosses a version skew carries no `enum`.** Users run
+`npx -y @owlmeans/viable-mcp@next` (the moving prerelease tag) against a separately deployed
+platform, so `ConnectCapabilitiesSchema.executors.items`
+is a bare string: a newer executor kind must stay an unused capability on an older platform, never
+a refused session. Apply the same reasoning to anything else a newer connector may send an older
+platform, and nowhere else — a closed set is worth more than a tolerant one everywhere both ends
+deploy together.
+
+## One declaration, elevated on both ends
+
+`connectEntrypoints(opts)` is the connector's whole HTTP and socket surface — paths, methods,
+schemas, parents — and the platform spreads it into its own entrypoints while the SDK elevates the
+same list into client entrypoints. That is what makes a path or a schema impossible to get wrong on
+one side only. Only what belongs to the DEPLOYMENT is injected: the guard alias, the ownership
+gate, the paid local-LLM gate (on the two routes that can turn that mode on) and the platform's own
+socket base.
+
+Adding a route means adding it here first, then elevating it on both sides. A route declared on one
+side alone is a 404 nobody can explain from the failing end.
+
+## Closed sets that mean something
+
+- **`ProjectArea`** — guest `/`, user `/frontoffice`, admin `/admin`, operator `/backoffice`. A
+  generated product's own roles map onto `user` or `operator`; there is no fifth area. `AREA_PATHS`,
+  `AREA_ACCESS` and `AREA_TIER` are total over it.
+- **`TargetLayout` + `TARGET_LAYOUTS`** — the integrity manifest is PER LAYOUT. A volume never
+  migrates, so a project created before the restructure stays on the legacy tree forever and must
+  verify **clean**; `TARGET_INTEGRITY_FILES` is the union over layouts so a caller has both probes
+  before it knows which tree it holds, and an absent layout reads as the CURRENT one.
+- **`SubProject`** — a ROLE vocabulary mapped per layout, never joined onto a path. Both
+  generations arrive on the wire at once, so the enum must stay total over what any live agent may
+  send, and no role but `Common` may resolve to the `common` directory.
+- **`ConversionStage`** — advanced only through `stageAfter` / `canEnter` / `decisionFor`. A stage
+  transition computed at a call site is how a conversion re-enters a stage it already paid for.
+- **`ModerationCategory`** — a wire contract with seven languages of wording behind it. A fifth
+  shape is PHRASED into one of the four, never added.
+
+## The conversion vocabulary is shared with three executors that walk the same tree
+
+The census, listing and relocation commands are one contract with three implementations — the
+SDK's local executor, the publisher's file helper, and the library's in-process helper — so
+anything they could disagree about is a constant HERE rather than a matching local copy:
+`CENSUS_SKIP_DIRS` (`node_modules`, `.git` — and deliberately not `dist`/`build`/`.next`, ordinary
+directory names an origin may keep sources in), `SOURCE_LIST_EXCLUSIONS` (the metadata directories
+plus `CONVERTED_ORIGIN_DIR`), `BINARY_PROBE_BYTES`, `CENSUS_MAX_HEAD_BYTES`, `RELOCATE_ALWAYS_KEEP`.
+The one thing they are allowed to differ about is stated rather than inherited: the platform's two
+keep what a volume it owns must not lose, the SDK's keeps what a DEVELOPER owns (`.viable`, the two
+`.env` files).
+
+`docs/conversion/` is likewise addressed only through the exported path builders
+(`CONVERSION_*_FILE`, `conversionStoryDoc`, `conversionSeedDoc`) — a conversion's own artifacts are
+read back by the purge, and a path spelled at a call site is a file the purge leaves behind.
+
+## The inquiry vocabulary is a deliberate COPY, and the ceiling is not
+
+`ConnectInquiryKind` / `InquiryPayload` / `InquiryAnswerPayload` mirror `@owlmeans/llm-common`'s
+`Inquiry` family, renamed so both vocabularies can be imported into one file and so `manager-api`,
+which does not depend on the model runtime, stays free of it. Values are byte-identical, so the
+platform's mapper is a widening rather than a translation table, and a test pins that — the same
+arrangement `ModelTask` has with `DelegatedTask`.
+
+The CEILING is not copied twice over: `CONNECT_INQUIRY_MAX_TEXT` equals
+`DEFAULT_INQUIRY_ANSWER_CHARS` and must stay equal, and `./convert`'s own
+`INQUIRY_STATE_TEXT_CHARS` — what a pipeline STATE may keep of an answer's prose, the rest going to
+`docs/conversion/inquiries.md` — equals its twin of the same name there. Two ceilings for one value means the layer with the larger one
+truncates silently at the smaller, and the caller records an assumption about an answer the person
+actually gave. Never introduce a local cap; import the one that exists.
+
+## Errors: declared here, phrased where they are read
+
+`ConnectError` and its family (`ConnectSessionNotFound`, `ConnectSessionGone`, `ConnectOpTimeout`,
+`ConnectOpRefused`, `LocalSlotUnsupported`, `ConnectOpUnknown`) are `ResilientError` classes with
+markers under `viable-connect:`. `ConnectSessionGone` is registered FATAL on the agent side: a run
+whose executor has gone away must stop at once rather than spend a retry ladder, and the step fails
+as an OUTCOME so the run row records where it stopped and `pipeline.resume` picks it up when a
+connector returns.
+
+The platform's own refusals — conversion, moderation, reserved names, integrity — are declared in
+the product repo, not here, so a consumer that cannot `instanceof` them matches by MARKER instead:
+`@owlmeans/viable-sdk`'s `REFUSALS` map and the manager's `useErrorPhrase` read the same substrings,
+which is what stops one refusal being phrased two ways. When a marker changes, both readers change
+with it.
+
+## Tests
+
+`bun test ./tests` — offline. `convert.spec.ts` (the three structural walks over the barrel, the
+conversion schemas compiling, a nullable enum accepting `null` under Ajv while still refusing an
+unknown member, the census classifiers and the stage transitions), `connect-convert.spec.ts` (the
+conversion routes at their paths and methods, hanging under the connector base and carrying no paid
+gate; capabilities accepting an executor kind this platform has never heard of; the answer and
+resume bodies), `design.spec.ts` (the design aggregate, staleness ranking, and the design schema
+refusing an undeclared field or an area outside the closed set).
+
+## Depends On
+
+- `@owlmeans/entrypoint`, `@owlmeans/route` — the entrypoint declarations
+- `@owlmeans/error` — the `Connect*` error family
+- `@owlmeans/llm-common` — `ExecutionEffort`/`ExecutionLevel`, `PromptPolicy`, `LlmPurpose`, and the
+  inquiry ceilings this package's copies are pinned to
+- `@owlmeans/agent-common` — the run and pipeline contracts a conversion's runs are declared against
+
+## Related
+
+- [[viable-sdk]] — the connector SDK written entirely against these contracts
+- [[viable-mcp]] — the npx stdio server built on that SDK
+- [[inquiry]] — the primitive `InquiryPayload` mirrors, and the one answer ceiling
+- [[llm-common]] — the contracts half of the model runtime
+- The DOMAIN rules for what these shapes mean — target areas and navigation, the scaffold, target
+  integrity, the metadata files, the converter — live in the downstream repos that implement them
+  (`target-areas`, `scaffolding`, `workload-integrity`, `viable-metadata`, `converter`). This skill
+  owns the CONTRACT: how a name is declared, and what refuses it.

package/build/agent/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './types.js';
+export * from './spectator/index.js';
+export * from './memory.js';
+//# sourceMappingURL=index.d.ts.map

package/build/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA"}

package/build/agent/index.js

@@ -0,0 +1,3 @@
+export * from './spectator/index.js';
+export * from './memory.js';
+//# sourceMappingURL=index.js.map

package/build/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA"}

package/build/agent/memory.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The agent-memory contracts, re-exported under viable's own name.
+ *
+ * The platform reaches `@owlmeans/agent-common` through here rather than importing it directly,
+ * for the same reason it reaches the LLM contracts through this package: the platform pins one
+ * version of the agent library, and a direct import would bind it to a second copy of the same
+ * types. Serializable contracts only — the runtime is `@owlmeans/agent`, re-exported by
+ * `@owlmeans/viable`.
+ */
+export { AgentRunStatus, conversationFor, truncateAt } from '@owlmeans/agent-common';
+export type { ConversationRef, ConversationEvent, ConversationEventInput, MemoryNode, MemoryEvent, MemoryEventInput, } from '@owlmeans/agent-common';
+//# sourceMappingURL=memory.d.ts.map

package/build/agent/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/agent/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAEpF,YAAY,EACV,eAAe,EAAE,iBAAiB,EAAE,sBAAsB,EAC1D,UAAU,EAAE,WAAW,EAAE,gBAAgB,GAC1C,MAAM,wBAAwB,CAAA"}

package/build/agent/memory.js

@@ -0,0 +1,11 @@
+/**
+ * The agent-memory contracts, re-exported under viable's own name.
+ *
+ * The platform reaches `@owlmeans/agent-common` through here rather than importing it directly,
+ * for the same reason it reaches the LLM contracts through this package: the platform pins one
+ * version of the agent library, and a direct import would bind it to a second copy of the same
+ * types. Serializable contracts only — the runtime is `@owlmeans/agent`, re-exported by
+ * `@owlmeans/viable`.
+ */
+export { AgentRunStatus, conversationFor, truncateAt } from '@owlmeans/agent-common';
+//# sourceMappingURL=memory.js.map

package/build/agent/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/agent/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA"}

package/build/agent/spectator/consts.d.ts

@@ -0,0 +1,9 @@
+/** Viable's concrete instance of the open `kind` field on a spectator entry. */
+export declare enum SpectatorEntryKind {
+    Coder = "coder",
+    Fixer = "fixer",
+    General = "general"
+}
+/** Owned by `@owlmeans/llm-common` — re-exported so consumers need one import only. */
+export { SpectatorContentType } from '@owlmeans/llm-common';
+//# sourceMappingURL=consts.d.ts.map

package/build/agent/spectator/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../../src/agent/spectator/consts.ts"],"names":[],"mappings":"AACA,gFAAgF;AAChF,oBAAY,kBAAkB;IAC5B,KAAK,UAAU;IACf,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED,uFAAuF;AACvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA"}

package/build/agent/spectator/consts.js

@@ -0,0 +1,10 @@
+/** Viable's concrete instance of the open `kind` field on a spectator entry. */
+export var SpectatorEntryKind;
+(function (SpectatorEntryKind) {
+    SpectatorEntryKind["Coder"] = "coder";
+    SpectatorEntryKind["Fixer"] = "fixer";
+    SpectatorEntryKind["General"] = "general";
+})(SpectatorEntryKind || (SpectatorEntryKind = {}));
+/** Owned by `@owlmeans/llm-common` — re-exported so consumers need one import only. */
+export { SpectatorContentType } from '@owlmeans/llm-common';
+//# sourceMappingURL=consts.js.map

package/build/agent/spectator/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../../../src/agent/spectator/consts.ts"],"names":[],"mappings":"AACA,gFAAgF;AAChF,MAAM,CAAN,IAAY,kBAIX;AAJD,WAAY,kBAAkB;IAC5B,qCAAe,CAAA;IACf,qCAAe,CAAA;IACf,yCAAmB,CAAA;AACrB,CAAC,EAJW,kBAAkB,KAAlB,kBAAkB,QAI7B;AAED,uFAAuF;AACvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA"}

package/build/agent/spectator/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './types.js';
+export * from './consts.js';
+//# sourceMappingURL=index.d.ts.map

package/build/agent/spectator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent/spectator/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA"}

package/build/agent/spectator/index.js

@@ -0,0 +1,2 @@
+export * from './consts.js';
+//# sourceMappingURL=index.js.map

package/build/agent/spectator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/spectator/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA"}

package/build/agent/spectator/types.d.ts

@@ -0,0 +1,13 @@
+import type { SpectatorEntry as LlmSpectatorEntry } from '@owlmeans/llm-common';
+import type { SpectatorEntryKind } from './consts.js';
+import type { PurposeMetadata } from '../types.js';
+/**
+ * The spectator record contracts are owned by `@owlmeans/llm-common`; viable narrows
+ * `kind` and `purpose` to its own enums on {@link SpectatorEntry}.
+ */
+export type { SpectatorArgument, SpectatorEntryMessage } from '@owlmeans/llm-common';
+export interface SpectatorEntry extends LlmSpectatorEntry {
+    kind: SpectatorEntryKind;
+    purpose: PurposeMetadata;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/agent/spectator/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agent/spectator/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,IAAI,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;GAGG;AACH,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAEpF,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,IAAI,EAAE,kBAAkB,CAAA;IACxB,OAAO,EAAE,eAAe,CAAA;CACzB"}

package/build/agent/spectator/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/agent/spectator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agent/spectator/types.ts"],"names":[],"mappings":""}

package/build/agent/types.d.ts

@@ -0,0 +1,10 @@
+import type { LlmPurpose } from '@owlmeans/llm-common';
+/**
+ * Observability metadata attached to every model call. Extends the generic
+ * `@owlmeans/llm-common` purpose (`type`, `dedication`) with viable's attribution fields.
+ */
+export interface PurposeMetadata extends LlmPurpose {
+    viableAgent?: string;
+    viableHelper?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/agent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB"}

package/build/agent/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":""}

package/build/areas/consts.d.ts

@@ -0,0 +1,88 @@
+import { AccessLevel } from '../dev/consts.js';
+/**
+ * The audiences a generated application serves.
+ *
+ * Every application has these four and only these four. A product's own roles are not new
+ * areas — they fall into one of these: anyone acting on the product's business process from
+ * the inside is an OPERATOR, anyone consuming the product's value as an end user is a USER.
+ * The set is closed so that navigation, access and preview all key off the same vocabulary;
+ * an application that needs a fifth audience needs a permission, not an area.
+ */
+export declare enum ProjectArea {
+    /** Unauthenticated. The public face of the application. */
+    Guest = "guest",
+    /** Signed-in end users — the front office. */
+    User = "user",
+    /** The owner. Holds {@link ADMIN_PERMISSION} and passes every gate. */
+    Admin = "admin",
+    /** Staff running the business process — the back office. */
+    Operator = "operator"
+}
+/**
+ * Where each area lives in the URL. One frontend, four prefixes — never four applications.
+ *
+ * The guest area owns `/` because it is the only area an anonymous visitor can reach, so it
+ * has to be what a bare hostname serves.
+ */
+export declare const AREA_PATHS: Record<ProjectArea, string>;
+/** Areas in menu/footer order — guest first, then the authenticated ones. */
+export declare const PROJECT_AREAS: ProjectArea[];
+/**
+ * The prefix of an AREA entrypoint — the parent every screen of that area hangs under.
+ *
+ * An area is addressed like a screen and rendered by the same router, so it has to be
+ * excluded explicitly wherever "the entrypoint of this screen" is being resolved — exactly
+ * as {@link ALIAS_PREFIX_WEB_LAYOUT} was.
+ */
+export declare const ALIAS_PREFIX_WEB_AREA = "web:area:";
+/**
+ * The owner's marker permission.
+ *
+ * It is a MARKER, not a scope: holding it means passing every gate, because the owner of a
+ * project is not a role inside it. A "limited admin" is therefore not this — it is an
+ * ordinary user holding some of the project's own permissions.
+ *
+ * Spelled as `<resource>--<action>` like every generated permission, on a resource name no
+ * domain entity can take.
+ */
+export declare const ADMIN_PERMISSION = "project--admin";
+/**
+ * The back office's marker permission.
+ *
+ * The operator area is where an organization's own staff work, and until this existed it was
+ * declared `guard(DEFAULT_GUARD)` alone — any signed-in person, which for a generated application
+ * means any visitor who typed an email address. The per-screen gates story development adds narrow
+ * particular screens; they cannot narrow the area, and a project with nothing developed yet has
+ * none of them at all, so the whole back office stood open by construction.
+ *
+ * It is a MARKER like {@link ADMIN_PERMISSION}, but it is NOT a bypass: it says a person belongs in
+ * the back office, and each screen's own permission still decides what they may do there. That AND
+ * is expressed by the area declaring the marker and the screen declaring its own — never by adding
+ * the marker to a screen's gate, where the OR between gate params would make it sufficient on its
+ * own and the screen's permission would stop meaning anything.
+ *
+ * Granted by the platform to the owning organization's people, exactly as the owner marker is, and
+ * to nobody else by default: a customer of the generated app is not staff.
+ */
+export declare const OPERATOR_PERMISSION = "project--operator";
+/**
+ * The access an area implies for the screens under it.
+ *
+ * Screens INHERIT this from the area declaration and never restate it. Only the operator
+ * area needs anything per screen — its gate names which permission that particular screen
+ * demands, which is the one thing an area cannot know.
+ */
+export declare const AREA_ACCESS: Record<ProjectArea, AccessLevel>;
+/**
+ * The grouping tag a story's area gives the permissions it declares.
+ *
+ * A TAG on the permission definition, never a segment of the permission's name. The gate treats a
+ * name as one opaque string, so putting a tier inside it would buy nothing at request time while
+ * making every existing permission a different permission — orphaning every grant already made
+ * against it, with no way to migrate the grant across.
+ *
+ * Two areas declare nothing. Guest is public and needs no permission. Admin's whole rule is
+ * {@link ADMIN_PERMISSION}, which the platform grants and no story ever registers.
+ */
+export declare const AREA_TIER: Record<ProjectArea, string | null>;
+//# sourceMappingURL=consts.d.ts.map

package/build/areas/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../src/areas/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C;;;;;;;;GAQG;AACH,oBAAY,WAAW;IACrB,2DAA2D;IAC3D,KAAK,UAAU;IACf,8CAA8C;IAC9C,IAAI,SAAS;IACb,uEAAuE;IACvE,KAAK,UAAU;IACf,4DAA4D;IAC5D,QAAQ,aAAa;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAKlD,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,aAAa,EAAE,WAAW,EAEtC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,cAAc,CAAA;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,mBAAmB,CAAA;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,WAAW,CAKxD,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAKxD,CAAA"}

package/build/areas/consts.js

@@ -0,0 +1,106 @@
+import { AccessLevel } from '../dev/consts.js';
+/**
+ * The audiences a generated application serves.
+ *
+ * Every application has these four and only these four. A product's own roles are not new
+ * areas — they fall into one of these: anyone acting on the product's business process from
+ * the inside is an OPERATOR, anyone consuming the product's value as an end user is a USER.
+ * The set is closed so that navigation, access and preview all key off the same vocabulary;
+ * an application that needs a fifth audience needs a permission, not an area.
+ */
+export var ProjectArea;
+(function (ProjectArea) {
+    /** Unauthenticated. The public face of the application. */
+    ProjectArea["Guest"] = "guest";
+    /** Signed-in end users — the front office. */
+    ProjectArea["User"] = "user";
+    /** The owner. Holds {@link ADMIN_PERMISSION} and passes every gate. */
+    ProjectArea["Admin"] = "admin";
+    /** Staff running the business process — the back office. */
+    ProjectArea["Operator"] = "operator";
+})(ProjectArea || (ProjectArea = {}));
+/**
+ * Where each area lives in the URL. One frontend, four prefixes — never four applications.
+ *
+ * The guest area owns `/` because it is the only area an anonymous visitor can reach, so it
+ * has to be what a bare hostname serves.
+ */
+export const AREA_PATHS = {
+    [ProjectArea.Guest]: '/',
+    [ProjectArea.User]: '/frontoffice',
+    [ProjectArea.Admin]: '/admin',
+    [ProjectArea.Operator]: '/backoffice',
+};
+/** Areas in menu/footer order — guest first, then the authenticated ones. */
+export const PROJECT_AREAS = [
+    ProjectArea.Guest, ProjectArea.User, ProjectArea.Admin, ProjectArea.Operator
+];
+/**
+ * The prefix of an AREA entrypoint — the parent every screen of that area hangs under.
+ *
+ * An area is addressed like a screen and rendered by the same router, so it has to be
+ * excluded explicitly wherever "the entrypoint of this screen" is being resolved — exactly
+ * as {@link ALIAS_PREFIX_WEB_LAYOUT} was.
+ */
+export const ALIAS_PREFIX_WEB_AREA = 'web:area:';
+/**
+ * The owner's marker permission.
+ *
+ * It is a MARKER, not a scope: holding it means passing every gate, because the owner of a
+ * project is not a role inside it. A "limited admin" is therefore not this — it is an
+ * ordinary user holding some of the project's own permissions.
+ *
+ * Spelled as `<resource>--<action>` like every generated permission, on a resource name no
+ * domain entity can take.
+ */
+export const ADMIN_PERMISSION = 'project--admin';
+/**
+ * The back office's marker permission.
+ *
+ * The operator area is where an organization's own staff work, and until this existed it was
+ * declared `guard(DEFAULT_GUARD)` alone — any signed-in person, which for a generated application
+ * means any visitor who typed an email address. The per-screen gates story development adds narrow
+ * particular screens; they cannot narrow the area, and a project with nothing developed yet has
+ * none of them at all, so the whole back office stood open by construction.
+ *
+ * It is a MARKER like {@link ADMIN_PERMISSION}, but it is NOT a bypass: it says a person belongs in
+ * the back office, and each screen's own permission still decides what they may do there. That AND
+ * is expressed by the area declaring the marker and the screen declaring its own — never by adding
+ * the marker to a screen's gate, where the OR between gate params would make it sufficient on its
+ * own and the screen's permission would stop meaning anything.
+ *
+ * Granted by the platform to the owning organization's people, exactly as the owner marker is, and
+ * to nobody else by default: a customer of the generated app is not staff.
+ */
+export const OPERATOR_PERMISSION = 'project--operator';
+/**
+ * The access an area implies for the screens under it.
+ *
+ * Screens INHERIT this from the area declaration and never restate it. Only the operator
+ * area needs anything per screen — its gate names which permission that particular screen
+ * demands, which is the one thing an area cannot know.
+ */
+export const AREA_ACCESS = {
+    [ProjectArea.Guest]: AccessLevel.Guest,
+    [ProjectArea.User]: AccessLevel.User,
+    [ProjectArea.Admin]: AccessLevel.Admin,
+    [ProjectArea.Operator]: AccessLevel.Permissioned,
+};
+/**
+ * The grouping tag a story's area gives the permissions it declares.
+ *
+ * A TAG on the permission definition, never a segment of the permission's name. The gate treats a
+ * name as one opaque string, so putting a tier inside it would buy nothing at request time while
+ * making every existing permission a different permission — orphaning every grant already made
+ * against it, with no way to migrate the grant across.
+ *
+ * Two areas declare nothing. Guest is public and needs no permission. Admin's whole rule is
+ * {@link ADMIN_PERMISSION}, which the platform grants and no story ever registers.
+ */
+export const AREA_TIER = {
+    [ProjectArea.Guest]: null,
+    [ProjectArea.User]: ProjectArea.User,
+    [ProjectArea.Admin]: null,
+    [ProjectArea.Operator]: ProjectArea.Operator,
+};
+//# sourceMappingURL=consts.js.map

package/build/areas/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../../src/areas/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,WASX;AATD,WAAY,WAAW;IACrB,2DAA2D;IAC3D,8BAAe,CAAA;IACf,8CAA8C;IAC9C,4BAAa,CAAA;IACb,uEAAuE;IACvE,8BAAe,CAAA;IACf,4DAA4D;IAC5D,oCAAqB,CAAA;AACvB,CAAC,EATW,WAAW,KAAX,WAAW,QAStB;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAgC;IACrD,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,GAAG;IACxB,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,cAAc;IAClC,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,QAAQ;IAC7B,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,aAAa;CACtC,CAAA;AAED,6EAA6E;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,QAAQ;CAC7E,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAA;AAEhD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAqC;IAC3D,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,KAAK;IACtC,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,IAAI;IACpC,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,KAAK;IACtC,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,YAAY;CACjD,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,SAAS,GAAuC;IAC3D,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI;IACzB,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,IAAI;IACpC,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI;IACzB,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ;CAC7C,CAAA"}

package/build/areas/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './types.js';
+export * from './consts.js';
+//# sourceMappingURL=index.d.ts.map

package/build/areas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/areas/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA"}

package/build/areas/index.js

@@ -0,0 +1,2 @@
+export * from './consts.js';
+//# sourceMappingURL=index.js.map