@owlmeans/viable-common 0.0.46 → 0.0.48-rc.0

package/tests/error-status.spec.ts

@@ -14,6 +14,7 @@ const DECLARED: Record<string, number | undefined> = {
   ConnectError: undefined,
   ConnectSessionNotFound: 404,
   ConnectOpUnknown: 404,
+  ConnectCallLost: 410,
   ConnectSessionGone: 409,
   LocalSlotUnsupported: 409,
   ConnectOpRefused: 422,
@@ -42,7 +43,7 @@ describe('viable-common refusals — declared HTTP statuses', () => {
     expect(classes.map(([name]) => name).sort()).toEqual(Object.keys(DECLARED).sort())
   })
 
-  test('balance 402, an absent target 404, a conflicting state 409, refused content 422, a consent or a confirmation only a person gives 428; faults nothing', () => {
+  test('balance 402, an absent target 404, a conflicting state 409, a lost outcome 410, refused content 422, a consent or a confirmation only a person gives 428; faults nothing', () => {
     for (const [name, Class] of classes) {
       expect([name, statusOf(new Class('x'))]).toEqual([name, DECLARED[name]])
     }

package/tests/iam-console.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import { aliasOf, protocols, type EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import { RouteMethod } from '@owlmeans/route'
+import { connect, ConnectPaidGate } from '../src/connect/consts.js'
+import {
+  ConnectIamGroupParamsSchema, ConnectIamMemberParamsSchema, ConnectIamOrganizationParamsSchema,
+  ConnectIamUserParamsSchema,
+} from '../src/connect/schemas.js'
+import { connectProtocols } from '../src/connect/entrypoints.js'
+import {
+  IAM_REFUSED, IamAssignGrantSchema, IamDefaultClass, IamDefinitionUpdateSchema, IamGrantMode, IamGroupMembersChangeSchema,
+  IamProjectUserInviteSchema, IamScopedSchema,
+} from '../src/iam-console/index.js'
+import { WorkloadKind } from '../src/slot/consts.js'
+
+const tree = connectProtocols({
+  guard: DEFAULT_GUARD,
+  gate: { alias: 'owner-gate', params: ['project'] },
+  accountGate: { alias: 'owner-gate', params: ['account'] },
+  paid: Object.fromEntries(Object.values(ConnectPaidGate).map(kind => [kind, { alias: `gate-${kind}`, params: [kind] }])),
+})
+const iamRoutes = protocols(tree.iam as never)
+const ajv = new Ajv({ strict: false })
+
+describe('@owlmeans/viable-common — the owner console contract', () => {
+  test('one schema set for both doors, a grant naming exactly one subject, and nullable enums carrying null', () => {
+    const grant = ajv.compile(IamAssignGrantSchema)
+    expect(grant({ profileId: 'shop:3vQB7B6MrGQZaxCuFg4oh', permission: 'order--view', mode: IamGrantMode.Blanket })).toBe(true)
+    expect(grant({ group: { entitySlug: 'acme', key: 'editors' }, permission: 'order--view' })).toBe(true)
+    expect(grant({ permission: 'order--view' })).toBe(false)
+    expect(grant({ profileId: 'p1', group: { entitySlug: 'acme', key: 'editors' }, permission: 'order--view' })).toBe(false)
+    expect(grant({ profileId: 'p1', permission: 'order--view', entityId: '64b7f0c2a1b2c3d4e5f60718' })).toBe(false)
+    // A connector sends an unset optional as null as readily as it drops the key.
+    expect(grant({ profileId: 'p1', permission: 'order--view', mode: null, scope: null })).toBe(true)
+    const update = ajv.compile(IamDefinitionUpdateSchema)
+    expect(update({ permission: 'order--view', defaultClass: IamDefaultClass.Owner })).toBe(true)
+    expect(update({ permission: 'order--view', defaultClass: 'everyone' })).toBe(false)
+    expect(ajv.compile(IamScopedSchema)({ scope: WorkloadKind.Production })).toBe(true)
+    expect(ajv.compile(IamScopedSchema)({ scope: 'staging' })).toBe(false)
+    expect(ajv.compile(IamProjectUserInviteSchema)({ email: 'a@b.test', entitySlug: 'acme' })).toBe(false)
+    expect(ajv.compile(IamGroupMembersChangeSchema)({ profileIds: [] })).toBe(false)
+    expect(IAM_REFUSED).toBe('iam-refused')
+  })
+})
+
+describe('@owlmeans/viable-common — the connector\'s IAM twins', () => {
+  test('every project route sits under the owned base with no paid gate; the customer-wide list under the account base', () => {
+    expect(iamRoutes).toHaveLength(22)
+    for (const protocol of iamRoutes) {
+      expect([protocol.alias, aliasOf(protocol.route.route.parent!), protocol.gate]).toEqual([protocol.alias, connect.base, undefined])
+      expect(protocol.route.route.path.startsWith('/project/:id/iam/')).toBe(true)
+    }
+    const users = tree.account.iam.users
+    expect([aliasOf(users.route.route.parent!), users.route.route.path, users.route.route.method])
+      .toEqual([connect.account.base, '/iam/users', RouteMethod.GET])
+    expect(tree.account.base.gate).toEqual({ alias: 'owner-gate', params: ['account'] })
+  })
+
+  test('every write is a POST carrying scope in its body — a remove included; every read takes it in the query', () => {
+    const propertiesOf = (schema: unknown): Record<string, unknown> =>
+      (schema as { properties?: Record<string, unknown> } | undefined)?.properties ?? {}
+    for (const protocol of iamRoutes as EntrypointProtocolDeclaration[]) {
+      const { method } = protocol.route.route
+      const schemas = protocol.contract?.requestSchemas
+      expect([protocol.alias, method === RouteMethod.GET || method === RouteMethod.POST]).toEqual([protocol.alias, true])
+      const carrier = method === RouteMethod.GET ? schemas?.query : schemas?.body
+      expect([protocol.alias, 'scope' in propertiesOf(carrier)]).toEqual([protocol.alias, true])
+      if (method === RouteMethod.GET) expect([protocol.alias, schemas?.body]).toEqual([protocol.alias, undefined])
+    }
+    expect(tree.iam.users.remove.contract?.requestSchemas?.body).toEqual(IamScopedSchema as never)
+    expect(tree.iam.grants.assign.contract?.requestSchemas?.body).toEqual(IamAssignGrantSchema as never)
+  })
+
+  test('the paths name the project as id, an organization by its slug, a subject and a group key — never a record id', () => {
+    const user = ajv.compile(ConnectIamUserParamsSchema)
+    expect(user({ id: 'p', profileId: 'shop:abc' })).toBe(true)
+    expect(user({ id: 'p', profileId: 'a/b' })).toBe(false)
+    const organization = ajv.compile(ConnectIamOrganizationParamsSchema)
+    expect(organization({ id: 'p', entitySlug: 'acme-corp' })).toBe(true)
+    expect(organization({ id: 'p', entitySlug: 'Acme' })).toBe(false)
+    expect(organization({ id: 'p', entitySlug: 'acme', entityId: 'x' })).toBe(false)
+    expect(ajv.compile(ConnectIamMemberParamsSchema)({ id: 'p', entitySlug: 'acme' })).toBe(false)
+    const group = ajv.compile(ConnectIamGroupParamsSchema)
+    expect(group({ id: 'p', entitySlug: 'acme', group: 'editors' })).toBe(true)
+    expect(group({ id: 'p', entitySlug: 'acme', group: 'a/b' })).toBe(false)
+  })
+})

package/tests/planning.spec.ts

@@ -246,6 +246,14 @@ describe('viable-common - the viable field schemas', () => {
     expect(project({ alias: 'slot-booker' })).toBe(false)
   })
 
+  test('a project carries ONE inference setting: a conversion has no mode of its own', () => {
+    // A conversion follows the session that drives it, like every other run; a card still
+    // carrying the removed per-conversion key is refused rather than silently kept.
+    expect(project({ connectLlmMode: 'local' })).toBe(true)
+    expect(project({ converterLlmMode: 'local' })).toBe(false)
+    expect(project({ converterLlmMode: null })).toBe(false)
+  })
+
   test('a project records a work kind from the closed set and a bounded case quote', () => {
     expect(project({ blueprintCase: 'work-management', workKind: 'crm', caseQuote: 'A CRM for ski resorts.' })).toBe(true)
     expect(project({ workKind: null, caseQuote: null })).toBe(true)

package/build/connect/ops.d.ts

@@ -1,189 +0,0 @@
-import type { SlotCommandPayload } from '../slot/index.js';
-import type { ConnectInquiryKind, ConnectOpErrorKind, ConnectOpKind, ModelTaskMode, ModelTaskResultKind, ModelTaskRole, ModelTier } from './consts.js';
-import type { ConnectServices } from './types.js';
-/**
- * One thing the platform asks a connector to do.
- *
- * Operations are addressed to a PROJECT, not to a session: a connector that restarts mid-run
- * re-attaches and is handed whatever is still pending, so an MCP server dying does not kill a
- * pipeline that is minutes into its work. `sessionId` records which session it was published to,
- * for tracing and for the redelivery counter — never for routing a result back.
- */
-export interface ConnectOp {
-    id: string;
-    projectId: string;
-    sessionId: string;
-    kind: ConnectOpKind;
-    payload: SlotCommandPayload | ModelTask | ConfigurePayload | InquiryPayload;
-    createdAt: string;
-    /** When the asker stops waiting. A connector past this may skip the work and say so. */
-    deadlineAt: string;
-    /** How many times this op has been delivered. > 1 means a connector reconnected. */
-    attempt: number;
-    deliveredAt?: string;
-}
-/**
- * The answer to exactly one operation.
- *
- * `ok: false` with `kind: 'malformed'` is a RETRYABLE outcome — the platform asks again, with the
- * problem quoted back. `'unavailable'` says the connector cannot do this at all and the run should
- * fail rather than spin.
- */
-export interface ConnectOpResult {
-    opId: string;
-    sessionId: string;
-    ok: boolean;
-    value?: unknown;
-    error?: ConnectOpError;
-}
-export interface ConnectOpError {
-    type: string;
-    message: string;
-    kind?: ConnectOpErrorKind;
-}
-/**
- * The configuration a local target needs, as file CONTENT rather than as keys.
- *
- * The platform composes it — it is the only side that knows the OIDC client, its secret and the
- * redirect URIs — and the connector writes it into the managed block of each named file, leaving
- * every line the user added alone. `probe` names the services the platform wants to know about
- * before it asks for a database migration or a boot check.
- */
-export interface ConfigurePayload {
-    files: ConfigureFile[];
-    probe: Array<keyof ConnectServices>;
-}
-export interface ConfigureFile {
-    /** Target-root-relative, e.g. `.env` or `sources/web/.env`. */
-    path: string;
-    /** The managed block's content. Written between the connector's own markers. */
-    content: string;
-}
-export interface ConfigureResult {
-    written: string[];
-    /**
-     * Keys the target still needs and the user must supply — a local database URL, say.
-     *
-     * Read exactly like the publisher's configure acknowledgement: a key with an EMPTY value counts
-     * as missing, because a push that ran before a secret existed leaves one behind.
-     */
-    missing: string[];
-    services: ConnectServices;
-}
-/**
- * One model call, handed to the parent agent.
- *
- * It carries everything a fresh subagent needs and nothing it does not: the persona as a system
- * prompt, the conversation so far, and the shape the answer must take. There is no platform
- * vocabulary in it — no pipeline, no step, no internal role semantics beyond a name and a tier —
- * because it is read by a model the platform does not own.
- */
-export interface ModelTask {
-    id: string;
-    projectId: string;
-    /** The platform role that asked. Informational; the tier is what decides the model. */
-    role: string;
-    tier: ModelTier;
-    /** Which attempt this is. > 0 means a previous answer was refused; `feedback` says why. */
-    attempt: number;
-    mode: ModelTaskMode;
-    system?: string;
-    messages: ModelTaskMessage[];
-    /** `Tools` mode: what the subagent may call. JSON Schema per tool. */
-    tools?: ModelTaskTool[];
-    /** `Tools` mode: force one tool, or leave the choice open. */
-    toolChoice?: ModelTaskToolChoice;
-    /** `Json` mode: the schema the single returned object must satisfy. */
-    outputSchema?: Record<string, unknown>;
-    /** A soft cap, stated so a parent can size its own call. */
-    maxOutputChars?: number;
-    /** Present on a retry: what was wrong with the previous answer. */
-    feedback?: string;
-    expiresAt: string;
-}
-export interface ModelTaskMessage {
-    role: ModelTaskRole;
-    content: string;
-    /** Assistant messages that called tools. */
-    toolCalls?: ModelTaskToolCall[];
-    /** Tool messages answer one call. */
-    toolCallId?: string;
-    /** Tool messages name the tool they answer. */
-    name?: string;
-}
-export interface ModelTaskTool {
-    name: string;
-    description?: string;
-    /** JSON Schema for the tool's arguments. */
-    parameters: Record<string, unknown>;
-}
-export type ModelTaskToolChoice = 'auto' | 'none' | {
-    name: string;
-};
-export interface ModelTaskToolCall {
-    id?: string;
-    name: string;
-    args: Record<string, unknown>;
-}
-/** What the parent's subagent produced. */
-export interface ModelTaskResult {
-    taskId: string;
-    kind: ModelTaskResultKind;
-    text?: string;
-    json?: unknown;
-    toolCalls?: ModelTaskToolCall[];
-    /** Why the parent could not answer. Treated as a malformed answer and retried. */
-    error?: string;
-    /** What the parent spent. Recorded for the trace; it costs the platform nothing. */
-    usage?: ModelTaskUsage;
-    /** What the parent actually ran. Display only. */
-    model?: string;
-}
-export interface ModelTaskUsage {
-    inputTokens?: number;
-    outputTokens?: number;
-}
-/** One option a {@link ConnectInquiryKind.Choice} question offers. */
-export interface ConnectInquiryOption {
-    value: string;
-    label: string;
-    description?: string;
-}
-/**
- * One question put to the person the connector is working for.
- *
- * It carries where it came from — the run and the step — because an answer is recorded
- * against the run that asked and re-read when that run resumes. `expiresAt` is what makes an
- * unanswered question fail its step instead of parking a project lock forever.
- */
-export interface InquiryPayload {
-    id: string;
-    projectId: string;
-    runId?: string;
-    /** The pipeline step that asked, so a resumed run can match the answer to the place it belongs. */
-    step?: string;
-    kind: ConnectInquiryKind;
-    question: string;
-    /** What the asker already knows, so the person is not asked to go and find it out. */
-    context?: string;
-    options?: ConnectInquiryOption[];
-    multiple?: boolean;
-    /** Whether a choice question also accepts text the options do not cover. */
-    allowText?: boolean;
-    /** What the asker will assume if nobody answers. Recorded as an assumption when it is used. */
-    default?: string | string[];
-    expiresAt: string;
-}
-/**
- * The answer to one question.
- *
- * `declined` is a real answer and not an absence: it says a person saw the question and chose not
- * to decide, which the asker records as an assumption rather than waiting out the timeout.
- */
-export interface InquiryAnswerPayload {
-    inquiryId: string;
-    value?: string | string[];
-    text?: string;
-    declined?: boolean;
-}
-//# sourceMappingURL=ops.d.ts.map

package/build/connect/ops.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../src/connect/ops.ts"],"names":[],"mappings":"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"}

package/build/connect/ops.js

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

package/build/connect/ops.js.map

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