@owlmeans/viable-common 0.0.39 → 0.0.41

package/src/areas/tenancy.ts

@@ -0,0 +1,69 @@
+import type { Blueprint } from '../blueprint/types.js'
+import { ProjectArea } from './consts.js'
+
+/**
+ * Whether a generated application splits its audiences into tenant ORGANIZATIONS.
+ *
+ * Two flags rather than one, because the two audiences split independently: one back office can
+ * serve end users who each belong to their own company (`users` only), every reseller can run its
+ * own staff over one shared public (`operators` only), and a B2B tool usually does both. An
+ * organization is an IAM-managed tenant — never a table the target keeps for itself.
+ *
+ * Both false is today's application: one organization, the project owner's, that every person acts in.
+ */
+export interface ProjectTenancy {
+  /** The staff of the back office are split into tenant organizations. */
+  operators: boolean
+  /** The end users of the front office are distributed across tenant organizations. */
+  users: boolean
+}
+
+/**
+ * A tenancy decision as the project card records it (`fields.tenancy`).
+ *
+ * The flags plus where they came from. `quotes` are the requester's OWN sentences, verbatim — the
+ * evidence a later reader (a person reviewing the board, a run asked to reconsider) checks the
+ * decision against, which a paraphrase would quietly replace with the model's reading of it.
+ * `by` says whether a model inferred it or the owner set it; `at` is when, an ISO timestamp.
+ */
+export interface ViableTenancyDecision extends ProjectTenancy {
+  quotes?: { operators?: string; users?: string }
+  by: 'model' | 'owner'
+  at: string
+}
+
+/** The longest requester sentence a tenancy decision quotes — a card refuses a longer one. */
+export const TENANCY_QUOTE_MAX = 1024
+
+/** A single-organization application — what every project is until a decision says otherwise. */
+export const NO_TENANCY: ProjectTenancy = Object.freeze({ operators: false, users: false })
+
+/**
+ * The tenancy of a resolved blueprint.
+ *
+ * Total, like `landingGatePreferenceOf`: an absent layer, an absent key and a value this deploy
+ * cannot read all answer {@link NO_TENANCY}. Only a literal `true` turns a flag on, because a flag
+ * read as on by mistake splits a product's people into organizations nobody asked for, while one
+ * read as off leaves the application exactly as it was before tenancy existed.
+ */
+export const tenancyOf = (blueprint?: Pick<Blueprint, 'experience'> | null): ProjectTenancy => {
+  const tenancy = blueprint?.experience?.tenancy
+  const operators = tenancy?.operators === true
+  const users = tenancy?.users === true
+
+  return operators || users ? Object.freeze({ operators, users }) : NO_TENANCY
+}
+
+/**
+ * Whether an AREA's people act inside a tenant organization.
+ *
+ * Guest has no organization to act in, and admin is the project owner, who stands above every
+ * tenant rather than inside one — so both are never tenanted, whatever the flags say.
+ */
+export const tenantedArea = (area: ProjectArea, tenancy: ProjectTenancy): boolean => {
+  switch (area) {
+    case ProjectArea.User: return tenancy.users === true
+    case ProjectArea.Operator: return tenancy.operators === true
+    default: return false
+  }
+}

package/src/blueprint/types.ts

@@ -1,3 +1,4 @@
+import type { ProjectTenancy } from '../areas/tenancy.js'
 import type { SubProject } from '../slot/consts.js'
 import type { ViableSkill } from '../skills/consts.js'
 import type { ViablePersona } from '../skills/roles.js'
@@ -21,7 +22,7 @@ import type { TopologyDescriptor } from '../topology/types.js'
  * OPTIONAL and says what its product should do for the people using it. Optional because a
  * blueprint registered before the layer existed — or a patch serialized into a run row — must keep
  * resolving: every reader asks through a helper that answers the default for an absent layer
- * ({@link landingGatePreferenceOf}).
+ * ({@link landingGatePreferenceOf}, `tenancyOf`).
  */
 export interface Blueprint {
   id: string
@@ -85,6 +86,14 @@ export enum LandingGatePreference {
  */
 export interface ExperienceLayer {
   landingGate: LandingGatePreference
+  /**
+   * Whether the product splits its audiences into tenant organizations.
+   *
+   * Written by resolution from {@link BlueprintRef.tenancy} — the project's own decision — and by
+   * no blueprint or case table, which cannot know it. Absent is a single-organization application;
+   * always read through `tenancyOf`.
+   */
+  tenancy?: ProjectTenancy
 }
 
 const LANDING_GATE_PREFERENCES = new Set<string>(Object.values(LandingGatePreference))
@@ -266,5 +275,14 @@ export interface BlueprintRef {
    * which is the only reading that cannot silently take a capability away from a live project.
    */
   case?: string
+  /**
+   * Whether the product splits its audiences into tenant organizations — the project card's
+   * decision, resolved into `experience.tenancy`.
+   *
+   * Flags rather than a key, because the decision is the project's own and no table could hold it;
+   * two booleans are still no artifact. Absent, or both false, applies nothing, so a run row of a
+   * project nobody decided for serializes exactly as it did before tenancy existed.
+   */
+  tenancy?: ProjectTenancy
   overrides?: BlueprintPatch
 }

package/src/connect/consts.ts

@@ -260,9 +260,9 @@ export const CONNECT_INQUIRY_MAX_TEXT = 2_000
 /**
  * How long a session survives without a sign of life.
  *
- * A connector refreshes its presence on every socket ping, every long-poll and every submit. Ten
- * minutes is generous on purpose: a parent agent running one model task in a subagent can be
- * silent for several, and expiring a session under it would fail a run that was progressing.
+ * A connector refreshes its presence on every long poll and every submit. Ten minutes is generous
+ * on purpose: a parent agent running one model task in a subagent can be silent for several, and
+ * expiring a session under it would fail a run that was progressing.
  */
 export const CONNECT_SESSION_EXPIRE_MS = 600_000
 
@@ -354,10 +354,6 @@ export const CONNECT_MARKER_DIR = '.viable'
 export const CONNECT_ENV_BEGIN = '# --- viable:managed ---'
 export const CONNECT_ENV_END = '# --- /viable:managed ---'
 
-/** Socket events a connector session carries. */
-export const CONNECT_EVENT_OP = 'connect:op'
-export const CONNECT_EVENT_SESSION = 'connect:session'
-
 /** Redis resource aliases the platform registers for the relay. */
 export const CONNECT_OP_PUBSUB = 'connect-op-pubsub'
 export const CONNECT_RESULT_PUBSUB = 'connect-result-pubsub'
@@ -381,14 +377,10 @@ export const RES_CONNECT_SESSION = 'connect-session'
  */
 export const connect = Object.freeze({
   base: 'viable:manager-api:connect:base',
-  capabilities: 'viable:manager-api:connect:capabilities',
   session: Object.freeze({
     open: 'viable:manager-api:connect:session:open',
     openDelegated: 'viable:manager-api:connect:session:open-delegated',
-    get: 'viable:manager-api:connect:session:get',
-    heartbeat: 'viable:manager-api:connect:session:heartbeat',
     close: 'viable:manager-api:connect:session:close',
-    socket: 'viable:manager-api:connect:session:socket',
   }),
   op: Object.freeze({
     pull: 'viable:manager-api:connect:op:pull',
@@ -402,10 +394,6 @@ export const connect = Object.freeze({
     attach: 'viable:manager-api:connect:project:attach',
     reinit: 'viable:manager-api:connect:project:reinit',
     modify: 'viable:manager-api:connect:project:modify',
-    settings: 'viable:manager-api:connect:project:settings',
-    llm: 'viable:manager-api:connect:project:llm',
-    /** The per-project converter inference mode. Separate from `llm`: it is not a paid capability. */
-    converterLlm: 'viable:manager-api:connect:project:converter-llm',
     /**
      * The project's own branding — copyright, organization, the two legal links, the Google tag.
      * The platform credit is deliberately NOT here: hiding it is a paid capability with its own
@@ -424,7 +412,6 @@ export const connect = Object.freeze({
     check: 'viable:manager-api:connect:convert:check',
     start: 'viable:manager-api:connect:convert:start',
     proceed: 'viable:manager-api:connect:convert:proceed',
-    cancel: 'viable:manager-api:connect:convert:cancel',
     status: 'viable:manager-api:connect:convert:status',
     purge: 'viable:manager-api:connect:convert:purge',
   }),

package/src/connect/entrypoints.ts

@@ -1,26 +1,23 @@
 import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
-import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
-import { route, RouteMethod, socket } from '@owlmeans/route'
-import { ConverterProjectLlmBodySchema } from '../convert/schemas.js'
+import { route, RouteMethod } from '@owlmeans/route'
 import { connect } from './consts.js'
 import {
   ConnectAttachBodySchema, ConnectConfirmBodySchema, ConnectConvertCreateBodySchema,
   ConnectConvertProceedBodySchema, ConnectCreateBodySchema, ConnectInquiryParamsSchema,
   ConnectModifyBodySchema, ConnectOpParamsSchema, ConnectOpResultSchema,
   ConnectPipelineParamsSchema, ConnectPipelineResumeBodySchema, ConnectProjectBrandingSaveSchema,
-  ConnectProjectIdSchema, ConnectProjectLlmBodySchema, ConnectSessionOpenSchema,
-  ConnectSessionParamsSchema, ConnectPullQuerySchema, ConnectStoryParamsSchema, InquiryAnswerSchema,
+  ConnectProjectIdSchema, ConnectSessionOpenSchema, ConnectSessionParamsSchema, ConnectPullQuerySchema,
+  ConnectStoryParamsSchema, InquiryAnswerSchema,
 } from './schemas.js'
 import type {
   ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
   ConnectCreateBody, ConnectInquiryAnswerBody, ConnectModifyBody,
   ConnectPipelineParams, ConnectPipelineResumeBody, ConnectProjectBranding,
-  ConnectProjectBrandingSave, ConnectProjectLlmBody, ConnectSessionOpen,
+  ConnectProjectBrandingSave, ConnectSessionOpen,
   ConnectPipelineState, ConnectProjectStatus, ConnectPullQuery, ConnectSessionParams,
   ConnectStoryStatus, ConversionStatusView, ConvertCheck,
 } from './types.js'
 import type { ConnectOpResult } from './ops.js'
-import type { ConverterProjectLlmBody } from '../convert/types.js'
 
 /**
  * What the platform injects when it mounts the connector routes.
@@ -37,19 +34,19 @@ export interface ConnectEntrypointOptions {
   /**
    * The gate that decides whether the caller may use the local-LLM mode.
    *
-   * Applied to the two routes that can turn it on — opening a delegated session and pinning a
-   * project to it. Everything else is free: `cloud` is the default and the platform writes it
-   * back by itself when a plan lapses.
+   * Applied to the one route that turns it on — opening a delegated session. Everything else is
+   * free: `cloud` is the default, and a project's own override is the platform's browser surface,
+   * not the connector's.
    */
   localLlm?: { alias: string, params: string[] }
-  /** The platform-owned websocket-base protocol that carries session updates. */
-  updateBase: EntrypointProtocol<OpenRequest, OpenValue>
   /** Path prefix; defaults to `/connect`. */
   path?: string
 }
 
 /**
- * Declare the connector's HTTP and socket surface.
+ * Declare the connector's HTTP surface — exactly the routes a connector calls: the session (long
+ * poll, no socket), the operation relay, projects, story status, generated files, conversion,
+ * inquiry answers and pipeline state.
  *
  * One immutable tree, mounted directly by the platform's entrypoint tree. Handlers are bound to these protocols
  * server-side and onto client entrypoints in the SDK — the same declarations both times, which is
@@ -69,11 +66,6 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
   return {
     base,
 
-    capabilities: protocol(
-      route(connect.capabilities, '/capabilities', { parent: base, method: RouteMethod.GET }),
-      contract(typed()),
-    ),
-
     // --- session ---------------------------------------------------------------------------
     session: {
     open: protocol(
@@ -86,29 +78,12 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
       }),
       contract.request({ body: typed<ConnectSessionOpen>(ConnectSessionOpenSchema) }, typed()), paid
     ),
-    get: protocol(
-      route(connect.session.get, '/session/:sessionId', {
-        parent: base, method: RouteMethod.GET
-      }),
-      contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema) }, typed())
-    ),
-    heartbeat: protocol(
-      route(connect.session.heartbeat, '/session/:sessionId/heartbeat', {
-        parent: base, method: RouteMethod.POST
-      }),
-      contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema) }, typed())
-    ),
     close: protocol(
       route(connect.session.close, '/session/:sessionId/close', {
         parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema) }, typed())
     ),
-    socket: protocol(
-      route(connect.session.socket, '/connect/:sessionId', socket({ parent: opts.updateBase })),
-      contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema) }, typed())
-    ),
-
     },
 
     // --- operations ------------------------------------------------------------------------
@@ -168,27 +143,6 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
       }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectModifyBody>(ConnectModifyBodySchema) }, typed<ConnectProjectStatus>())
     ),
-    settings: protocol(
-      route(connect.project.settings, '/project/:id/settings', {
-        parent: base, method: RouteMethod.GET
-      }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed())
-    ),
-    llm: protocol(
-      route(connect.project.llm, '/project/:id/llm', {
-        parent: base, method: RouteMethod.POST
-      }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectProjectLlmBody>(ConnectProjectLlmBodySchema) }, typed()), paid
-    ),
-    converterLlm: protocol(
-      route(connect.project.converterLlm, '/project/:id/converter-llm', {
-        parent: base, method: RouteMethod.POST,
-      }),
-      contract.request({
-        params: typed<{ id: string }>(ConnectProjectIdSchema),
-        body: typed<ConverterProjectLlmBody>(ConverterProjectLlmBodySchema),
-      }, typed()),
-    ),
     // Under `base` like every sibling — the guard and the ownership gate — and never under the
     // paid gate: saving branding is free, and the paid credit switch is not reachable from here.
     branding: {
@@ -252,10 +206,6 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
         body: typed<ConnectConvertProceedBody>(ConnectConvertProceedBodySchema),
       }, typed<ConversionStatusView>()),
     ),
-    cancel: protocol(
-      route(connect.convert.cancel, '/convert/:id/cancel', { parent: base, method: RouteMethod.POST }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConversionStatusView>()),
-    ),
     status: protocol(
       route(connect.convert.status, '/convert/:id', { parent: base, method: RouteMethod.GET }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConversionStatusView>()),

package/src/connect/references.ts

@@ -3,13 +3,11 @@ import type { RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
 import type { EntrypointReference } from '@owlmeans/context'
 import { connect } from './consts.js'
 import type { ConnectOp, ConnectOpResult } from './ops.js'
-import type { ConverterProjectLlmBody } from '../convert/index.js'
 import type {
-  ConnectAttachBody, ConnectCapabilitiesView, ConnectConfirmBody, ConnectCreateBody,
-  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectInquiryAnswerBody,
-  ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams, ConnectPipelineResumeBody,
-  ConnectPipelineState, ConnectProjectBranding, ConnectProjectBrandingSave, ConnectProjectLlmBody,
-  ConnectProjectSettings, ConnectProjectStatus, ConnectProjectSummary, ConnectPullQuery,
+  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectConvertCreateBody,
+  ConnectConvertProceedBody, ConnectInquiryAnswerBody, ConnectModifyBody, ConnectOpSubmission,
+  ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState, ConnectProjectBranding,
+  ConnectProjectBrandingSave, ConnectProjectStatus, ConnectProjectSummary, ConnectPullQuery,
   ConnectSessionOpen, ConnectSessionParams, ConnectSessionView, ConnectStoryStatus,
   ConversionStatusView, ConvertCheck,
 } from './types.js'
@@ -18,12 +16,9 @@ type ConnectReference<Request extends RequestShape, Response> =
   EntrypointReference<RegisteredEntrypoint<Request, Response>>
 
 export interface ConnectReferences {
-  capabilities: ConnectReference<{}, ConnectCapabilitiesView>
   session: {
     open: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
     openDelegated: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
-    get: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
-    heartbeat: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
     close: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
   }
   op: {
@@ -40,11 +35,6 @@ export interface ConnectReferences {
     attach: ConnectReference<{ body: ConnectAttachBody }, ConnectProjectStatus>
     reinit: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
     modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>
-    settings: ConnectReference<{ params: { id: string } }, ConnectProjectSettings>
-    llm: ConnectReference<{ params: { id: string }, body: ConnectProjectLlmBody }, ConnectProjectSettings>
-    converterLlm: ConnectReference<{
-      params: { id: string }, body: ConverterProjectLlmBody
-    }, ConnectProjectSettings>
     branding: {
       get: ConnectReference<{ params: { id: string } }, ConnectProjectBranding>
       save: ConnectReference<{
@@ -65,7 +55,6 @@ export interface ConnectReferences {
     proceed: ConnectReference<{
       params: { id: string }, body: ConnectConvertProceedBody
     }, ConversionStatusView>
-    cancel: ConnectReference<{ params: { id: string } }, ConversionStatusView>
     status: ConnectReference<{ params: { id: string } }, ConversionStatusView>
     purge: ConnectReference<{ params: { id: string } }, ConversionStatusView>
   }
@@ -88,12 +77,9 @@ export interface ConnectReferences {
  * aliases to UI or domain code.
  */
 export const connectRef: ConnectReferences = {
-  capabilities: entrypointRef<{}, ConnectCapabilitiesView>(connect.capabilities),
   session: {
     open: entrypointRef<{ body: ConnectSessionOpen }, ConnectSessionView>(connect.session.open),
     openDelegated: entrypointRef<{ body: ConnectSessionOpen }, ConnectSessionView>(connect.session.openDelegated),
-    get: entrypointRef<{ params: ConnectSessionParams }, ConnectSessionView>(connect.session.get),
-    heartbeat: entrypointRef<{ params: ConnectSessionParams }, ConnectSessionView>(connect.session.heartbeat),
     close: entrypointRef<{ params: ConnectSessionParams }, ConnectSessionView>(connect.session.close),
   },
   op: {
@@ -110,13 +96,6 @@ export const connectRef: ConnectReferences = {
     attach: entrypointRef<{ body: ConnectAttachBody }, ConnectProjectStatus>(connect.project.attach),
     reinit: entrypointRef<{ params: { id: string } }, ConnectProjectStatus>(connect.project.reinit),
     modify: entrypointRef<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>(connect.project.modify),
-    settings: entrypointRef<{ params: { id: string } }, ConnectProjectSettings>(connect.project.settings),
-    llm: entrypointRef<{
-      params: { id: string }, body: ConnectProjectLlmBody
-    }, ConnectProjectSettings>(connect.project.llm),
-    converterLlm: entrypointRef<{
-      params: { id: string }, body: ConverterProjectLlmBody
-    }, ConnectProjectSettings>(connect.project.converterLlm),
     branding: {
       get: entrypointRef<{ params: { id: string } }, ConnectProjectBranding>(connect.project.branding.get),
       save: entrypointRef<{
@@ -136,7 +115,6 @@ export const connectRef: ConnectReferences = {
     proceed: entrypointRef<{
       params: { id: string }, body: ConnectConvertProceedBody
     }, ConversionStatusView>(connect.convert.proceed),
-    cancel: entrypointRef<{ params: { id: string } }, ConversionStatusView>(connect.convert.cancel),
     status: entrypointRef<{
       params: { id: string }
     }, ConversionStatusView>(connect.convert.status),

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'])
+  })
+})