@owlmeans/viable-common 0.0.38 → 0.0.40

package/src/connect/types.ts

@@ -186,8 +186,7 @@ export interface ConnectProfileSettingsView extends ConnectProfileSettings {
    * work: a conversion reads somebody else's whole repository, which is the one case where handing
    * the inference to the parent agent is the cheap default rather than the experimental option.
    *
-   * OPTIONAL for the same reason {@link ConnectCapabilitiesView.defaults} carries `converterLlm`
-   * optionally: the two converter fields are answered by a platform build that does not exist yet,
+   * OPTIONAL: the two converter fields are answered by a platform build that does not exist yet,
    * and this package is consumed by the platform through a workspace link rather than a published
    * range — a required field here is a compile error in every handler that already returns this
    * view. Tightened to required once the platform's conversion handlers fill them.
@@ -251,26 +250,6 @@ export interface ConnectProjectBranding {
  */
 export interface ConnectProjectBrandingSave extends Partial<ConnectProjectBranding> {}
 
-/** What the platform tells a connector about itself. */
-export interface ConnectCapabilitiesView {
-  /** Tier → the platform role names that will be asked for at that tier. */
-  tiers: Record<ModelTier, string[]>
-  /** Whether this caller may open a local-LLM session. */
-  localLlm: boolean
-  /**
-   * The default mode for a new session, resolved from the caller's settings.
-   *
-   * `converterLlm` is OPTIONAL: an older platform does not send it, and a client that treated its
-   * absence as a value would pin every conversion to whatever its own default happened to be.
-   */
-  defaults: { target: ConnectTarget, llm: ConnectLlm, converterLlm?: ConnectLlm }
-  limits: {
-    pullWaitMs: number
-    modelTaskTimeoutMs: number
-    maxPending: number
-  }
-}
-
 /** Attach an existing project to a session. */
 export interface ConnectAttachBody {
   projectId?: string

package/src/dev/consts.ts

@@ -10,6 +10,22 @@ export enum AccessLevel {
   Admin = 'admin',
 }
 
+/**
+ * Who holds a permission without anybody granting it — the default CLASS of its definition.
+ *
+ * Evaluated by the IAM when it issues claims, never copied onto rows, so a person who joins an
+ * organization later holds what its members hold with nothing written for them. `User` is every
+ * signed-in person of the application; `Member` and `Owner` are the members and the owners of the
+ * organization being acted in, and therefore mean anything only for an organization-bound
+ * permission. `None` is the ordinary permission: held only where it was granted.
+ */
+export enum PermissionDefault {
+  None = 'none',
+  User = 'user',
+  Member = 'member',
+  Owner = 'owner',
+}
+
 /**
  * Alias prefixes of the entrypoints a generated project declares.
  *

package/src/dev/schemas.ts

@@ -80,7 +80,10 @@ export const EntrypointRefListSchema: JSONSchemaType<{entries: EntrypointRef[]}>
   additionalProperties: false
 }
 
-export const AccessBlockSchema: JSONSchemaType<AccessBlock> = {
+/** The part of an {@link AccessBlock} a model is asked for. */
+type ModelAccessBlock = Omit<AccessBlock, 'defaults' | 'entityScoped'>
+
+const ModelAccessBlockSchema: JSONSchemaType<ModelAccessBlock> = {
   type: "object",
   title: "AccessBlock",
   description: "Object with permissions array and access level",
@@ -119,6 +122,15 @@ export const AccessBlockSchema: JSONSchemaType<AccessBlock> = {
   additionalProperties: false
 }
 
+/**
+ * The access block a model writes.
+ *
+ * It names only what a model is asked for: `defaults` and `entityScoped` are written by code and
+ * must never reach a prompt, which `tests/access-schema.spec.ts` pins byte for byte. A value it
+ * admits is still an {@link AccessBlock}, because both code-written keys are optional.
+ */
+export const AccessBlockSchema = ModelAccessBlockSchema as unknown as JSONSchemaType<AccessBlock>
+
 export const AccessListSchema: JSONSchemaType<AccessList> = {
   type: "object",
   title: "AccessList",

package/src/dev/types.ts

@@ -1,4 +1,4 @@
-import type { AccessLevel } from "./consts.js"
+import type { AccessLevel, PermissionDefault } from "./consts.js"
 
 export interface SourceFile {
   path: string
@@ -33,6 +33,20 @@ export interface AccessBlock {
   level: AccessLevel
   /** Gate params safe for every newly signed-in user; a subset of permissions. */
   defaultEnabledPermissions?: string[]
+  /**
+   * The default class of each permission this block names, keyed by the gate param with its
+   * `@<routeParam>` selector stripped — the name the definition is registered under.
+   *
+   * Written by CODE, never by a model: `AccessBlockSchema` does not carry it, so a model answer
+   * never holds one, and what decides it is the project's tenancy and the area, not a reading of
+   * the story.
+   */
+  defaults?: Record<string, PermissionDefault>
+  /**
+   * Whether the permissions of this block are bound to the organization being acted in, rather than
+   * held everywhere. Written by code, like {@link AccessBlock.defaults}.
+   */
+  entityScoped?: boolean
 }
 
 /**

package/src/planning/schemas.ts

@@ -1,6 +1,7 @@
 import type { JSONSchemaType } from 'ajv'
 import { CODE_MAX } from '@owlmeans/planning'
 import { ProjectArea } from '../areas/consts.js'
+import { TENANCY_QUOTE_MAX } from '../areas/tenancy.js'
 import { StoryKind } from '../ba/consts.js'
 import { ConnectLlm, ConnectTarget } from '../connect/consts.js'
 import { ProjectOriginSchema } from '../convert/schemas.js'
@@ -40,6 +41,30 @@ export const ViableProjectFieldsSchema = {
       required: ['at'],
       additionalProperties: false,
     },
+    // An absent `tenancy` is "never decided"; a recorded one always carries both flags, so a
+    // reader never has to guess what a missing flag meant.
+    tenancy: {
+      type: 'object',
+      nullable: true,
+      properties: {
+        operators: { type: 'boolean' },
+        users: { type: 'boolean' },
+        quotes: {
+          type: 'object',
+          nullable: true,
+          properties: {
+            operators: { type: 'string', minLength: 1, maxLength: TENANCY_QUOTE_MAX, nullable: true },
+            users: { type: 'string', minLength: 1, maxLength: TENANCY_QUOTE_MAX, nullable: true },
+          },
+          required: [],
+          additionalProperties: false,
+        },
+        by: { type: 'string', enum: ['model', 'owner'] },
+        at: { type: 'string', minLength: 1, maxLength: 32 },
+      },
+      required: ['operators', 'users', 'by', 'at'],
+      additionalProperties: false,
+    },
   },
   required: [],
   additionalProperties: false,

package/src/planning/types.ts

@@ -1,5 +1,6 @@
 import type { Card, Project, Specification } from '@owlmeans/planning'
 import type { ProjectArea } from '../areas/consts.js'
+import type { ViableTenancyDecision } from '../areas/tenancy.js'
 import type { StoryKind } from '../ba/consts.js'
 import type { ConnectLlm, ConnectTarget } from '../connect/consts.js'
 import type { ProjectOrigin } from '../convert/types.js'
@@ -42,6 +43,14 @@ export type ViableProjectFields = {
    * "none" and no later run would ask again. `at` is when it was decided, an ISO timestamp.
    */
   landing?: ViableLandingDecision
+  /**
+   * Whether the target splits its operators and its end users into tenant organizations.
+   *
+   * ABSENT means never decided and reads as a single-organization application, exactly as every
+   * project before tenancy. It reaches a run through the blueprint reference (`BlueprintRef.tenancy`)
+   * only when a flag is on.
+   */
+  tenancy?: ViableTenancyDecision
 }
 
 /** The recorded landing-gate decision — see {@link ViableProjectFields.landing}. */

package/tests/access-schema.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test'
+import { createHash } from 'node:crypto'
+import { AccessBlockSchema, AccessLevel, AccessListSchema, PermissionDefault } from '../src/index.js'
+import type { AccessBlock } from '../src/index.js'
+
+const sha256 = (value: unknown): string =>
+  createHash('sha256').update(JSON.stringify(value)).digest('hex')
+
+// The model-facing schemas, byte for byte. They are rendered into the access prompts verbatim and
+// handed to the model as its answer contract, so a change here changes what every model is asked —
+// update these only together with the prompts that read them.
+const ACCESS_BLOCK_SHA256 = '577c8406a73604128ff016a35fe918960d1316a1a24fe4737be31e41478c6ca8'
+const ACCESS_LIST_SHA256 = '80b3ab836718ce69c97e9854f647f2b5ed794ec4b871e86ae94b0fad4bf68a50'
+
+describe('viable-common - the access schema a model is asked for', () => {
+  test('names only the model-written keys, never the code-written defaults or binding', () => {
+    expect(Object.keys(AccessBlockSchema.properties ?? {})).toEqual(
+      ['permissions', 'level', 'defaultEnabledPermissions']
+    )
+    expect(JSON.stringify(AccessListSchema)).not.toContain('entityScoped')
+    expect(JSON.stringify(AccessListSchema)).not.toContain('"defaults"')
+  })
+
+  test('is byte-identical to the schema the access prompts were written against', () => {
+    expect(sha256(AccessBlockSchema)).toBe(ACCESS_BLOCK_SHA256)
+    expect(sha256(AccessListSchema)).toBe(ACCESS_LIST_SHA256)
+  })
+
+  test('an access block still carries the code-written keys as data', () => {
+    const block: AccessBlock = {
+      permissions: ['enquiry--view@enquiryId'], level: AccessLevel.Permissioned,
+      defaults: { 'enquiry--view': PermissionDefault.Member }, entityScoped: true,
+    }
+    expect(block.defaults).toEqual({ 'enquiry--view': 'member' })
+    expect(Object.values(PermissionDefault)).toEqual(['none', 'user', 'member', 'owner'])
+  })
+})

package/tests/connect-convert.spec.ts

@@ -1,8 +1,8 @@
 import { describe, expect, test } from 'bun:test'
 import Ajv from 'ajv'
 import addFormats from 'ajv-formats'
-import { RouteMethod, route } from '@owlmeans/route'
-import { aliasOf, openProtocol, protocols } from '@owlmeans/entrypoint'
+import { RouteMethod } from '@owlmeans/route'
+import { aliasOf, protocols } from '@owlmeans/entrypoint'
 import { connect, ConnectInquiryKind, ConnectOpKind } from '../src/connect/consts.js'
 import { connectProtocols } from '../src/connect/entrypoints.js'
 import { connectRef } from '../src/connect/references.js'
@@ -20,7 +20,6 @@ const entrypoints = () => connectProtocols({
   guard: 'test-guard',
   gate: { alias: 'test-gate', params: ['id'] },
   localLlm: { alias: 'test-paid-llm', params: ['id'] },
-  updateBase: openProtocol(route('test:update:base', '/update')),
 })
 
 const entrypointOf = (alias: string) => {
@@ -102,11 +101,9 @@ describe('viable-common - the conversion additions to the connector contract', (
       [connect.convert.check, '/convert/:id/check', RouteMethod.GET],
       [connect.convert.start, '/convert/:id/start', RouteMethod.POST],
       [connect.convert.proceed, '/convert/:id/proceed', RouteMethod.POST],
-      [connect.convert.cancel, '/convert/:id/cancel', RouteMethod.POST],
       [connect.convert.status, '/convert/:id', RouteMethod.GET],
       [connect.convert.purge, '/convert/:id/purge', RouteMethod.POST],
       [connect.inquiry.answer, '/project/:id/inquiry/:inquiryId', RouteMethod.POST],
-      [connect.project.converterLlm, '/project/:id/converter-llm', RouteMethod.POST],
       [connect.files.list, '/project/:id/files', RouteMethod.GET],
     ]
 
@@ -122,21 +119,18 @@ describe('viable-common - the conversion additions to the connector contract', (
     expect(connectRef.convert.check.alias).toBe(connect.convert.check)
     expect(connectRef.convert.start.alias).toBe(connect.convert.start)
     expect(connectRef.convert.proceed.alias).toBe(connect.convert.proceed)
-    expect(connectRef.convert.cancel.alias).toBe(connect.convert.cancel)
     expect(connectRef.convert.status.alias).toBe(connect.convert.status)
     expect(connectRef.convert.purge.alias).toBe(connect.convert.purge)
     expect(connectRef.inquiry.answer.alias).toBe(connect.inquiry.answer)
-    expect(connectRef.project.converterLlm.alias).toBe(connect.project.converterLlm)
     expect(connectRef.files.list.alias).toBe(connect.files.list)
   })
 
   test('the conversion routes hang under the connector base and carry no paid gate', () => {
     // Delegated inference is the DEFAULT for a conversion, not an experimental capability — so
-    // unlike `project.llm`, nothing here sits behind the local-LLM gate.
-    expect(entrypointOf(connect.project.llm).gate?.alias).toBe('test-paid-llm')
+    // unlike the delegated session, nothing here sits behind the local-LLM gate.
+    expect(entrypointOf(connect.session.openDelegated).gate?.alias).toBe('test-paid-llm')
 
-    const gated = [...Object.values(connect.convert), connect.inquiry.answer,
-      connect.project.converterLlm]
+    const gated = [...Object.values(connect.convert), connect.inquiry.answer]
     for (const alias of gated) {
       expect(entrypointOf(alias).gate, alias).toBeUndefined()
       expect(aliasOf(routeOf(alias).parent!), alias).toBe(connect.base)

package/tests/connect-entrypoints.spec.ts

@@ -1,30 +1,48 @@
 import { describe, expect, test } from 'bun:test'
 import Ajv from 'ajv'
-import { aliasOf, openProtocol, protocols } from '@owlmeans/entrypoint'
+import { aliasOf, protocols } from '@owlmeans/entrypoint'
 import { DEFAULT_GUARD } from '@owlmeans/auth-common'
-import { route, RouteMethod } from '@owlmeans/route'
+import { RouteMethod, RouteProtocols } from '@owlmeans/route'
 import { connect, CONNECT_BRANDING_GOOGLE_TAG_MAX } from '../src/connect/consts.js'
 import { ConnectProjectBrandingSaveSchema } from '../src/connect/schemas.js'
 import { connectProtocols } from '../src/connect/entrypoints.js'
 import { connectRef } from '../src/connect/references.js'
 
 describe('@owlmeans/viable-common — connector protocol tree', () => {
-  const tree = connectProtocols({
-    guard: DEFAULT_GUARD,
-    updateBase: openProtocol(route('manager:update', '/update')),
-  })
+  const tree = connectProtocols({ guard: DEFAULT_GUARD })
 
   test('exports named immutable declarations and a complete flat materialization view', () => {
     expect(tree.base.alias).toBe(connect.base)
     expect(tree.session.open.alias).toBe(connect.session.open)
-    expect(tree.project.llm.alias).toBe(connect.project.llm)
-    expect(tree.project.converterLlm.alias).toBe(connect.project.converterLlm)
     expect(tree.story.status.alias).toBe(connect.story.status)
     expect(tree.convert.proceed.alias).toBe(connect.convert.proceed)
     expect(tree.inquiry.answer.alias).toBe(connect.inquiry.answer)
     expect(tree.files.list.alias).toBe(connect.files.list)
-    expect(protocols(tree)).toHaveLength(34)
-    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(34)
+    expect(protocols(tree)).toHaveLength(26)
+    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(26)
+  })
+
+  test('declares exactly the routes a connector calls — every alias, reference and path, and no socket', () => {
+    const declared = protocols(tree)
+    const addresses = declared.filter(protocol => protocol.route.route.method != null)
+      .map(protocol => `${protocol.route.route.method!.toUpperCase()} ${protocol.route.route.path}`).sort()
+
+    expect(addresses).toEqual([
+      'GET /convert/:id', 'GET /convert/:id/check', 'GET /pipeline/:id/:runId', 'GET /project',
+      'GET /project/:id/branding', 'GET /project/:id/files', 'GET /project/:id/status',
+      'GET /project/:id/story/:storyId/status', 'GET /session/:sessionId/ops',
+      'POST /convert', 'POST /convert/:id/proceed', 'POST /convert/:id/purge', 'POST /convert/:id/start',
+      'POST /pipeline/:id/:runId/resume', 'POST /project', 'POST /project/:id/branding',
+      'POST /project/:id/confirm', 'POST /project/:id/inquiry/:inquiryId', 'POST /project/:id/modify',
+      'POST /project/:id/reinit', 'POST /project/attach', 'POST /session', 'POST /session/:sessionId/close',
+      'POST /session/:sessionId/ops/:opId', 'POST /session/delegated',
+    ])
+    expect(declared.every(protocol => protocol.route.route.protocol !== RouteProtocols.SOCKET)).toBe(true)
+    // The alias table, the tree and the typed references name the same routes.
+    const leaves = (value: object): string[] => Object.values(value).flatMap(entry =>
+      typeof entry === 'string' ? [entry] : 'alias' in entry ? [entry.alias as string] : leaves(entry))
+    expect(leaves(connect).sort()).toEqual(declared.map(protocol => protocol.alias).sort())
+    expect(leaves(connectRef).sort()).toEqual(declared.map(protocol => protocol.alias).filter(alias => alias !== connect.base).sort())
   })
 
   test('reads and saves a project\'s branding at one path, under the owned base and no paid gate', () => {
@@ -32,7 +50,6 @@ describe('@owlmeans/viable-common — connector protocol tree', () => {
       guard: DEFAULT_GUARD,
       gate: { alias: 'test-gate', params: ['owner'] },
       localLlm: { alias: 'test-paid-llm', params: ['cap'] },
-      updateBase: openProtocol(route('manager:update', '/update')),
     })
     const get = paid.project.branding.get
     const save = paid.project.branding.save
@@ -45,9 +62,11 @@ describe('@owlmeans/viable-common — connector protocol tree', () => {
     expect(save.route.route.method).toBe(RouteMethod.POST)
     expect(aliasOf(get.route.route.parent)).toBe(connect.base)
     expect(aliasOf(save.route.route.parent)).toBe(connect.base)
-    // The paid local-LLM gate sits on its own two routes; branding carries no gate of its own and
-    // inherits only the base's guard and ownership gate.
-    expect(paid.project.llm.gate?.alias).toBe('test-paid-llm')
+    // The paid local-LLM gate sits on the delegated session alone; branding carries no gate of its
+    // own and inherits only the base's guard and ownership gate.
+    expect(paid.session.openDelegated.gate?.alias).toBe('test-paid-llm')
+    expect(protocols(paid).filter(protocol => protocol.gate?.alias === 'test-paid-llm'))
+      .toEqual([paid.session.openDelegated])
     expect(get.gate).toBeUndefined()
     expect(save.gate).toBeUndefined()
     expect(connectRef.project.branding.save.alias).toBe(connect.project.branding.save)

package/tests/planning.spec.ts

@@ -276,6 +276,32 @@ describe('viable-common - the viable field schemas', () => {
     expect(project({ landing: { story: 'US-ABC12' } })).toBe(false)
     expect(project({ landing: { story: 'US-ABC12', at, reason: 'best fit' } })).toBe(false)
   })
+
+  test('a project records a tenancy decision with both flags, who decided it and when', () => {
+    expect(project({ tenancy: { operators: false, users: true, by: 'model', at } })).toBe(true)
+    expect(project({
+      tenancy: {
+        operators: true, users: true, by: 'owner', at,
+        quotes: { operators: 'Each agency manages its own staff.', users: null },
+      },
+    })).toBe(true)
+    expect(project({ tenancy: null })).toBe(true)
+  })
+
+  test('a project refuses a partial tenancy decision, an unknown decider and a stray key', () => {
+    expect(project({ tenancy: { users: true, by: 'model', at } })).toBe(false)
+    expect(project({ tenancy: { operators: true, users: false, at } })).toBe(false)
+    expect(project({ tenancy: { operators: true, users: false, by: 'model' } })).toBe(false)
+    expect(project({ tenancy: { operators: 'yes', users: false, by: 'model', at } })).toBe(false)
+    expect(project({ tenancy: { operators: true, users: false, by: 'agent', at } })).toBe(false)
+    expect(project({ tenancy: { operators: true, users: false, by: 'model', at, reason: 'b2b' } })).toBe(false)
+    expect(project({
+      tenancy: { operators: true, users: false, by: 'model', at, quotes: { staff: 'x' } },
+    })).toBe(false)
+    expect(project({
+      tenancy: { operators: true, users: false, by: 'model', at, quotes: { operators: 'x'.repeat(1025) } },
+    })).toBe(false)
+  })
 })
 
 describe('viable-common - the viable card helpers', () => {

package/tests/tenancy.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test'
+import { NO_TENANCY, ProjectArea, tenancyOf, tenantedArea } from '../src/index.js'
+import { LandingGatePreference } from '../src/blueprint/index.js'
+
+const experience = (tenancy: unknown) =>
+  ({ experience: { landingGate: LandingGatePreference.Allow, tenancy: tenancy as never } })
+
+describe('viable-common - the project tenancy', () => {
+  test('NO_TENANCY is both flags off and cannot be changed', () => {
+    expect(NO_TENANCY).toEqual({ operators: false, users: false })
+    expect(Object.isFrozen(NO_TENANCY)).toBe(true)
+  })
+
+  test('tenancyOf answers NO_TENANCY for no blueprint, no layer, no key and an unreadable value', () => {
+    expect(tenancyOf()).toBe(NO_TENANCY)
+    expect(tenancyOf(null)).toBe(NO_TENANCY)
+    expect(tenancyOf({})).toBe(NO_TENANCY)
+    expect(tenancyOf({ experience: { landingGate: LandingGatePreference.Allow } })).toBe(NO_TENANCY)
+    expect(tenancyOf(experience(null))).toBe(NO_TENANCY)
+    expect(tenancyOf(experience('both'))).toBe(NO_TENANCY)
+    expect(tenancyOf(experience({ operators: 'yes', users: 1 }))).toBe(NO_TENANCY)
+    expect(tenancyOf(experience({ operators: false, users: false }))).toBe(NO_TENANCY)
+    expect(tenancyOf({ experience: 'flat' as never })).toBe(NO_TENANCY)
+  })
+
+  test('tenancyOf reads a literal true per flag, and an absent flag as off', () => {
+    expect(tenancyOf(experience({ operators: true, users: false }))).toEqual({ operators: true, users: false })
+    expect(tenancyOf(experience({ users: true }))).toEqual({ operators: false, users: true })
+    const both = tenancyOf(experience({ operators: true, users: true }))
+    expect(both).toEqual({ operators: true, users: true })
+    expect(Object.isFrozen(both)).toBe(true)
+  })
+
+  test('tenantedArea: user follows users, operator follows operators, guest and admin never', () => {
+    const all = { operators: true, users: true }
+    expect(tenantedArea(ProjectArea.User, all)).toBe(true)
+    expect(tenantedArea(ProjectArea.Operator, all)).toBe(true)
+    expect(tenantedArea(ProjectArea.Guest, all)).toBe(false)
+    expect(tenantedArea(ProjectArea.Admin, all)).toBe(false)
+
+    expect(tenantedArea(ProjectArea.User, { operators: true, users: false })).toBe(false)
+    expect(tenantedArea(ProjectArea.Operator, { operators: false, users: true })).toBe(false)
+    for (const area of Object.values(ProjectArea)) {
+      expect(tenantedArea(area, NO_TENANCY)).toBe(false)
+    }
+    expect(tenantedArea('partner' as ProjectArea, all)).toBe(false)
+  })
+})