@xema/omni-protocol 0.1.20 → 0.1.22

package/dist/index.d.ts

@@ -111,8 +111,8 @@ export interface Manifest<C extends Channel = Channel> {
     phaseLabels?: TaskPhaseLabels;
     /** Keyed by `taskType`. An entry replaces the channel default outright rather than merging. */
     taskTypePresentation?: Record<string, TaskTypePresentation>;
-    /** The structure's tiers, relabelling or extending `DEFAULT_TIERS` by id. Omitted for the typical four. */
-    tiers?: TierDeclaration[];
+    /** The organisation's whole ladder, stated outright, `person` included. Omitted for the typical four, `DEFAULT_TIERS`. */
+    orgTiers?: TierDeclaration[];
 }
 export interface SecretStore {
     get(key: string): Promise<string | undefined>;
@@ -530,7 +530,7 @@ export interface TaskAssisting {
 }
 /**
  * A tier of the organisation's structure, by the id its manifest declares -- or one of the four
- * every organisation has, `DEFAULT_TIERS`, which a manifest relabels or adds to. The protocol
+ * a typical organisation has, `DEFAULT_TIERS`, when the manifest declares no ladder. The protocol
  * never describes the chain: which tiers a person passes through is the structure's to know.
  */
 export type Tier = string;
@@ -540,8 +540,8 @@ export interface TierDeclaration {
     label: string;
 }
 /**
- * The tiers a typical organisation has. A manifest that declares `tiers` relabels any of these
- * by id and may add its own; one that declares none has exactly these.
+ * The tiers a typical organisation has: the ladder in force when a manifest declares no
+ * `orgTiers`. A manifest that declares any states its whole ladder outright.
  */
 export declare const DEFAULT_TIERS: readonly [{
     readonly id: "org";
@@ -556,7 +556,7 @@ export declare const DEFAULT_TIERS: readonly [{
     readonly id: "person";
     readonly label: "You";
 }];
-/** The tiers in force for a manifest: the defaults, relabelled or extended by what it declares. */
+/** The ladder in force for a manifest: exactly what it declares, or the defaults when it declares none. */
 export declare function effectiveTiers(declared: readonly TierDeclaration[] | undefined): TierDeclaration[];
 /**
  * Something the queue could allow, locked above the person: the tier that made it unchangeable,

package/dist/index.js

@@ -51,8 +51,8 @@ export function isAllowedBrowserUrl(url) {
     }
 }
 /**
- * The tiers a typical organisation has. A manifest that declares `tiers` relabels any of these
- * by id and may add its own; one that declares none has exactly these.
+ * The tiers a typical organisation has: the ladder in force when a manifest declares no
+ * `orgTiers`. A manifest that declares any states its whole ladder outright.
  */
 export const DEFAULT_TIERS = [
     { id: "org", label: "Your organisation" },
@@ -60,12 +60,9 @@ export const DEFAULT_TIERS = [
     { id: "team", label: "Your team" },
     { id: "person", label: "You" },
 ];
-/** The tiers in force for a manifest: the defaults, relabelled or extended by what it declares. */
+/** The ladder in force for a manifest: exactly what it declares, or the defaults when it declares none. */
 export function effectiveTiers(declared) {
-    const byId = new Map(DEFAULT_TIERS.map(tier => [tier.id, tier]));
-    for (const tier of declared ?? [])
-        byId.set(tier.id, tier);
-    return [...byId.values()];
+    return [...(declared ?? DEFAULT_TIERS)];
 }
 // ---------------------------------------------------------------------------
 // Task commands.

package/dist/testing.js

@@ -169,7 +169,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     let disconnectWasClean = false;
     try {
         authenticationState = await authentication.state();
-        const tiers = effectiveTiers(adapter.manifest.tiers).map(tier => tier.id);
+        const tiers = effectiveTiers(adapter.manifest.orgTiers).map(tier => tier.id);
         violations.push(...validateAuthenticationState(authenticationState, "authentication", { tiers }));
         if (authenticationState.status !== "authenticated") {
             throw new Error(`Adapter contract exercise requires authenticated test state, received ${authenticationState.status}`);

package/dist/validation.js

@@ -311,25 +311,35 @@ export function validateManifest(manifest, path = "manifest") {
             }
         }
     }
-    if (manifest.tiers !== undefined) {
-        if (!Array.isArray(manifest.tiers)) {
-            into.add("manifest.tiers.shape", `${path}.tiers`, "tiers must be an array when present");
+    if (manifest.orgTiers !== undefined) {
+        if (!Array.isArray(manifest.orgTiers)) {
+            into.add("manifest.orgTiers.shape", `${path}.orgTiers`, "orgTiers must be an array when present");
         }
         else {
             const ids = new Set();
-            manifest.tiers.forEach((tier, index) => {
-                const at = `${path}.tiers[${index}]`;
+            let wellFormed = true;
+            manifest.orgTiers.forEach((tier, index) => {
+                const at = `${path}.orgTiers[${index}]`;
                 if (!isPlainObject(tier)) {
-                    into.add("manifest.tier.shape", at, "each tier must be an object with an id and a label");
+                    into.add("manifest.orgTier.shape", at, "each tier must be an object with an id and a label");
+                    wellFormed = false;
                     return;
                 }
-                if (into.filled(tier.id, "manifest.tier.id", `${at}.id`, "a tier needs an id")) {
-                    if (ids.has(tier.id))
-                        into.add("manifest.tier.unique", `${at}.id`, `duplicate tier: ${tier.id}`);
+                if (into.filled(tier.id, "manifest.orgTier.id", `${at}.id`, "a tier needs an id")) {
+                    if (ids.has(tier.id)) {
+                        into.add("manifest.orgTier.unique", `${at}.id`, `duplicate tier: ${tier.id}`);
+                        wellFormed = false;
+                    }
                     ids.add(tier.id);
                 }
-                into.filled(tier.label, "manifest.tier.label", `${at}.label`, "a tier needs the label a desk shows for it");
+                else
+                    wellFormed = false;
+                if (!into.filled(tier.label, "manifest.orgTier.label", `${at}.label`, "a tier needs the label a desk shows for it"))
+                    wellFormed = false;
             });
+            if (wellFormed && !ids.has("person")) {
+                into.add("manifest.orgTiers.person", `${path}.orgTiers`, "a declared ladder states the whole ladder and must include person, the subject of every resolution");
+            }
         }
     }
     if (manifest.taskTypePresentation !== undefined) {
@@ -488,7 +498,7 @@ function validateLockedByInto(value, rule, path, tiers, into) {
     if (!into.filled(value, rule, path, "lockedBy names the tier that locked it"))
         return;
     into.require(value !== "person", `${rule}.person`, path, "a person never locks their own value");
-    into.require(tierIds(tiers).includes(value), `${rule}.unknown`, path, `${String(value)} is not a tier this manifest declares: the defaults are ${DEFAULT_TIER_IDS.join(", ")}`);
+    into.require(tierIds(tiers).includes(value), `${rule}.unknown`, path, `${String(value)} is not a tier this manifest declares: in force are ${tierIds(tiers).join(", ")}`);
 }
 /** `{ lockedBy, reason? }` standing in for a value: who locked it, and a reason if given. */
 function validateLockedInto(value, rule, path, tiers, into) {
@@ -512,9 +522,9 @@ function validateResolvedInto(value, rule, path, tiers, into) {
 function manifestTiers(manifest) {
     if (!isPlainObject(manifest))
         return undefined;
-    const declared = Array.isArray(manifest.tiers)
-        ? manifest.tiers.filter((tier) => isPlainObject(tier) && typeof tier.id === "string")
-        : [];
+    const declared = Array.isArray(manifest.orgTiers)
+        ? manifest.orgTiers.filter((tier) => isPlainObject(tier) && typeof tier.id === "string")
+        : undefined;
     return effectiveTiers(declared).map(tier => tier.id);
 }
 const CUSTOM_RENDERS = membersOf({ inline: true, page: true });

package/guide.md

@@ -176,7 +176,7 @@ type Manifest<C extends Channel = Channel> = {
   idleCapabilities?: IdleCapabilities<C>;
   phaseLabels?: TaskPhaseLabels;
   taskTypePresentation?: Record<string, TaskTypePresentation>;
-  tiers?: TierDeclaration[];
+  orgTiers?: TierDeclaration[];
 };
 ```
 
@@ -708,13 +708,17 @@ the person settles the value for everyone below it, and where nothing enforces t
 tier that says anything wins. The protocol names a tier by the id the manifest declares for it and
 never describes the chain between them: which tiers a person passes through is the structure's to
 know. A typical organisation has four, and they are the defaults — `DEFAULT_TIERS`: `org`, `site`,
-`team`, `person`, each with the label a desk shows — which `Manifest.tiers` relabels by id (a
-provider whose "site" means something else says what it means) or extends with tiers of its own;
-a manifest that declares none has exactly the four. `lockedBy` is any tier in force except
-`person`, who never locks their own value; `setBy` is any tier in force, or `provisioning`, the
-protocol's own word for "no tier has said anything and the provider's default applies". A host
-renders "who decided" from the declared labels and needs no others. What the wire carries is the
-resolution:
+`team`, `person`, each with the label a desk shows. A structure that differs states its whole
+ladder in `Manifest.orgTiers`, `person` included: what the list carries is in force, and what it
+leaves out does not exist — a structure with no site tier declares `org`, `team`, `person`, and
+`site` is refused on its wire. A declared tier is one the provider's own store actually resolves
+at: a label with no policy behind it decides nothing. A manifest that declares none has exactly
+the four. `lockedBy` is any tier in force except `person`, who never locks their own value;
+`setBy` is any tier in force, or `provisioning`, the protocol's word for "no tier has said
+anything and the provider's own configuration supplied the value" — the provider speaking, never
+Omni's provisioning file, which does not reach the wire. A host renders "who decided" from the
+declared labels and needs no others, and validates every republished `authenticated` state
+against them, not only the sign-in. What the wire carries is the resolution:
 
 - **`lockedBy`** — a tier above the person made this value theirs to keep. A person never locks
   their own value, and the queue is not a tier: what the queue does not allow at all is absent.
@@ -1349,7 +1353,7 @@ compile time.
 | `idleCapabilities` | Declares actions Omni may offer while the agent has no active task, such as voice dialing. Task controls do not belong here. |
 | `phaseLabels` | Optional static adapter-defined display names for canonical `TaskPhase` values. They cannot vary at runtime. |
 | `taskTypePresentation` | Optional static adapter-defined presentation keyed by exact `taskType`. It names the item and its optional agent-facing reference. |
-| `tiers` | The structure's tiers as the provider calls them, each with the label a desk shows for "who decided". Relabels any of `DEFAULT_TIERS` by id and may add others; omitted for the typical four. See **Who decides what an agent may do**. |
+| `orgTiers` | The organisation's whole ladder as the provider calls it, each tier with the label a desk shows for "who decided". Stated outright, `person` included: what it leaves out does not exist. Omitted for the typical four, `DEFAULT_TIERS`. See **Who decides what an agent may do**. |
 
 ### Authentication methods
 
@@ -1867,7 +1871,7 @@ Returns the provider's complete authoritative state at one point in time.
   order.
 - `tasks` must contain every task currently owned by this agent for this provider.
 - A snapshot replaces Omni's state for this provider; it is not a partial patch.
-- The adapter may return synchronously when it already holds current live values, as Jema does, or
+- The adapter may return synchronously when it already holds current live values, or
   asynchronously when it must obtain state.
 
 ### `Connection.subscribe(listener)`
@@ -3568,7 +3572,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateScheduledActivity(activity)` | Required activity fields and start/end ordering. |
 | `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `ready` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `ready` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
 | `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
-| `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. |
+| `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. Omni applies it to every state a session publishes — the republished as much as the first. |
 
 Each returns `ProtocolViolation[]` rather than throwing, so a caller can report every problem at
 once. A violation carries a stable `rule` id such as `task.browser.url.scheme`, the `path` it was

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",