@owlmeans/viable-common 0.0.4

package/src/design/schemas.ts

@@ -0,0 +1,384 @@
+import type { JSONSchemaType } from 'ajv'
+
+import { ProjectArea } from '../areas/consts.js'
+import { StoryActor, StoryAgentKind } from './runtime.js'
+import type { StoryDesignAgent, StoryDesignJob } from './runtime.js'
+import type { StoryDesign } from './types.js'
+
+/**
+ * The design shape, validated where the shape is DEFINED.
+ *
+ * A record store that carried a strict `$jsonSchema` over this would have to be edited in another
+ * repository every time this library added a field - which is exactly how a slot-metadata field
+ * once reached the wire, missed the schema, and took out every newly provisioned slot with the
+ * spec still green. So the payload is stored as JSON text and validated with THIS, by the store,
+ * before the write.
+ *
+ * `additionalProperties: false` at every level, so a field the library dropped cannot survive in
+ * an old revision and be silently read back by code that no longer knows what it meant.
+ */
+
+const specs = {
+  type: 'object',
+  properties: {
+    ux: { type: 'string' },
+    ui: { type: 'string' },
+  },
+  required: ['ux', 'ui'],
+  additionalProperties: false,
+} as const
+
+export const StoryDesignSchema: JSONSchemaType<StoryDesign> = {
+  type: 'object',
+  title: 'StoryDesign',
+  description: 'Everything a user story will be, decided before any of it is written',
+  properties: {
+    version: { type: 'integer', minimum: 1 },
+    code: { type: 'string' },
+    narrative: { type: 'string' },
+    area: { type: 'string', enum: Object.values(ProjectArea) },
+    reserved: {
+      type: 'object',
+      properties: {
+        section: { type: 'string', nullable: true },
+        screen: { type: 'string', nullable: true },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+    entities: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          description: { type: 'string' },
+          dir: { type: 'string' },
+        },
+        required: ['name', 'description', 'dir'],
+        additionalProperties: false,
+      },
+    },
+    screens: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          definition: { type: 'string' },
+          path: { type: 'string' },
+          alias: { type: 'string' },
+          url: { type: 'string' },
+          parent: { type: 'string' },
+          section: { type: 'string', nullable: true },
+          adopted: { type: 'boolean' },
+          specs,
+          components: { type: 'array', items: { type: 'string' } },
+        },
+        required: [
+          'name', 'definition', 'path', 'alias', 'url', 'parent', 'adopted', 'specs', 'components',
+        ],
+        additionalProperties: false,
+      },
+    },
+    components: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          definition: { type: 'string' },
+          path: { type: 'string' },
+          viewModelPath: { type: 'string' },
+          adopted: { type: 'boolean' },
+          screen: { type: 'string' },
+          entities: { type: 'array', items: { type: 'string' } },
+          specs,
+        },
+        required: [
+          'name', 'definition', 'path', 'viewModelPath', 'adopted', 'screen', 'entities', 'specs',
+        ],
+        additionalProperties: false,
+      },
+    },
+    types: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          entity: { type: 'string' },
+          purpose: { type: 'string' },
+          components: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['path', 'entity', 'purpose', 'components'],
+        additionalProperties: false,
+      },
+    },
+    resources: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          entity: { type: 'string' },
+          type: { type: 'string' },
+          alias: { type: 'string' },
+          purpose: { type: 'string' },
+        },
+        required: ['path', 'entity', 'type', 'alias', 'purpose'],
+        additionalProperties: false,
+      },
+    },
+    models: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          entities: { type: 'array', items: { type: 'string' } },
+          solution: { type: 'string', nullable: true },
+        },
+        required: ['path', 'entities'],
+        additionalProperties: false,
+      },
+    },
+    api: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          entity: { type: 'string' },
+          type: { type: 'string' },
+          model: { type: 'string' },
+          endpoints: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                alias: { type: 'string' },
+                method: { type: 'string' },
+                path: { type: 'string' },
+                purpose: { type: 'string' },
+              },
+              required: ['alias', 'method', 'path', 'purpose'],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ['path', 'entity', 'type', 'model', 'endpoints'],
+        additionalProperties: false,
+      },
+    },
+    stores: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          entity: { type: 'string' },
+          type: { type: 'string' },
+          api: { type: 'string' },
+        },
+        required: ['path', 'entity', 'type', 'api'],
+        additionalProperties: false,
+      },
+    },
+    transitions: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          from: { type: 'string' },
+          to: { type: 'string' },
+          initiator: { type: 'string' },
+          action: { type: 'string' },
+          type: { type: 'string' },
+        },
+        required: ['from', 'to', 'initiator', 'action', 'type'],
+        additionalProperties: false,
+      },
+    },
+    access: {
+      type: 'object',
+      properties: {
+        // Keyed by entrypoint ALIAS, and the aliases come back from a model matched against
+        // generated code - so the keys cannot be enumerated here, only their shape.
+        list: { type: 'object', additionalProperties: true, required: [] },
+        resolvedAt: { type: 'object', additionalProperties: { type: 'string' }, required: [] },
+      },
+      required: ['list', 'resolvedAt'],
+      additionalProperties: false,
+    },
+    // Optional: a design written before the gate existed carries none, and every reader takes
+    // "absent" as "none of it" — which is both the safe answer and the true one.
+    runtime: {
+      type: 'object',
+      nullable: true,
+      properties: {
+        actor: { type: 'string', enum: Object.values(StoryActor) },
+        worker: { type: 'boolean' },
+        kv: { type: 'boolean' },
+        feedback: { type: 'string', nullable: true },
+        jobs: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              queue: { type: 'string' },
+              name: { type: 'string' },
+              path: { type: 'string' },
+              purpose: { type: 'string' },
+              reason: { type: 'string' },
+              idempotency: { type: 'string' },
+            },
+            required: ['queue', 'name', 'path', 'purpose', 'reason', 'idempotency'],
+            additionalProperties: false,
+          },
+        },
+        agents: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              alias: { type: 'string' },
+              path: { type: 'string' },
+              purpose: { type: 'string' },
+              kind: { type: 'string', enum: Object.values(StoryAgentKind) },
+              job: { type: 'string', nullable: true },
+            },
+            required: ['alias', 'path', 'purpose', 'kind'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['actor', 'worker', 'kv', 'jobs', 'agents'],
+      additionalProperties: false,
+    },
+    provenance: {
+      type: 'object',
+      properties: {
+        designedAt: { type: 'string' },
+        narrativeHash: { type: 'string' },
+        projectHash: { type: 'string' },
+        registryHash: { type: 'string' },
+        paths: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string' },
+              hash: { type: 'string' },
+            },
+            required: ['path', 'hash'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['designedAt', 'narrativeHash', 'projectHash', 'registryHash', 'paths'],
+      additionalProperties: false,
+    },
+  },
+  required: [
+    'version', 'code', 'narrative', 'area', 'reserved', 'entities', 'screens', 'components',
+    'types', 'resources', 'models', 'api', 'stores', 'transitions', 'access', 'provenance',
+  ],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<StoryDesign>
+
+/**
+ * What the runtime gate answers with.
+ *
+ * Deliberately NOT `StoryDesignRuntime`: the model is asked what the story NEEDS, and the derived
+ * half — whether that adds up to a worker, whether an agent has a job to run in — is the helper's
+ * to compute. A model asked for `worker: boolean` beside a job list can answer with the two
+ * disagreeing, and there is no honest way to pick a winner.
+ */
+export const RuntimeDecisionSchema = {
+  type: 'object',
+  properties: {
+    kv: {
+      type: 'boolean',
+      description: 'True only for data with an expiry, a lock, a counter or a fan-out, and a '
+        + 'small bounded key set. Records the product owns and queries belong in Postgres.',
+    },
+    feedback: {
+      type: 'string',
+      description: 'Where a person sees the progress of this queued work — the screen or story '
+        + 'that shows it. Empty when nothing is queued.',
+    },
+    jobs: {
+      type: 'array',
+      description: 'Empty for almost every story. One entry per unit of work that genuinely '
+        + 'cannot run inside a request.',
+      items: {
+        type: 'object',
+        properties: {
+          queue: { type: 'string', description: 'The queue name. Reuse one the project has.' },
+          name: {
+            type: 'string',
+            description: 'What the job DOES, as `<entity>:<action>` — `contract:analyze`, '
+              + '`report:build`. The alias, the route, the processor file name and the handler '
+              + 'symbol are all derived from it, so give the action and not an identifier.',
+          },
+          path: { type: 'string', description: 'Ignored — the processor file is derived from the '
+            + 'name, so the two can never disagree. Give the name and leave this empty.' },
+          purpose: { type: 'string', description: 'What it does, in one sentence.' },
+          reason: {
+            type: 'string',
+            description: 'WHICH of the listed reasons makes this impossible inside a request. '
+              + 'Name the property; do not restate the story.',
+          },
+          idempotency: {
+            type: 'string',
+            description: 'Concretely how running it twice is safe. A worker can die mid-job.',
+          },
+        },
+        required: ['queue', 'name', 'path', 'purpose', 'reason', 'idempotency'],
+        additionalProperties: false,
+      },
+    },
+    agents: {
+      type: 'array',
+      description: 'Empty unless the work is genuinely a language task the application performs.',
+      items: {
+        type: 'object',
+        properties: {
+          alias: { type: 'string', description: 'lowerCamelCase alias in the app agent registry.' },
+          path: { type: 'string', description: 'Module file name, without a directory.' },
+          purpose: { type: 'string' },
+          kind: {
+            type: 'string',
+            enum: Object.values(StoryAgentKind),
+            description: '`call` for one prompt and one answer — the default and almost '
+              + 'always right; `pipeline` for steps this application names in advance; `agent` '
+              + 'only when the number of steps cannot be predicted and tool choice is the '
+              + "model's own judgement.",
+          },
+          job: {
+            type: 'string',
+            description: 'The `name` of the job that runs it, copied from the job list above. '
+              + 'An agent never runs on the request path, so a job that calls a model must name '
+              + 'the agent it runs and that agent must name the job back.',
+          },
+        },
+        required: ['alias', 'path', 'purpose', 'kind', 'job'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['kv', 'feedback', 'jobs', 'agents'],
+  additionalProperties: false,
+  // Structured-output schema rather than a validated record shape: AJV's `JSONSchemaType` would
+  // demand `minItems` on every array to prove non-emptiness, and the whole point of these arrays
+  // is that they are usually empty.
+} as unknown as JSONSchemaType<RuntimeDecision>
+
+/** What the gate answers with — the model's half of {@link StoryDesignRuntime}. */
+export interface RuntimeDecision {
+  kv: boolean
+  feedback: string
+  jobs: StoryDesignJob[]
+  agents: StoryDesignAgent[]
+}

package/src/design/types.ts

@@ -0,0 +1,191 @@
+import type { ProjectArea } from '../areas/consts.js'
+import type { StoryDesignRuntime } from './runtime.js'
+import type { AccessList } from '../dev/types.js'
+import type { UXTransition } from '../ux/types.js'
+
+/**
+ * One screen, as the design decided it.
+ *
+ * Every name here is ALLOCATED — through the project's name registry — rather than invented by
+ * whoever writes the file later. That is the difference between a design and a wish: two runs days
+ * apart address the same file because the design named it, not because they guessed alike.
+ */
+export interface StoryDesignScreen {
+  /** The UX name, `{section}/{part}/{purpose}`. Not a path. */
+  name: string
+  /** The path-shaped stem the file and its aliases are derived from. */
+  definition: string
+  path: string
+  /** The entrypoint alias. This is the key access rules and the navigation registry use. */
+  alias: string
+  url: string
+  /** The AREA entrypoint this screen hangs under. Deterministic from the story's area. */
+  parent: string
+  /**
+   * The top-menu group. ALWAYS the scaffold's reservation, never derived from `name`.
+   *
+   * The menu group is decided once, when the application is drawn, so a story's screens land in
+   * the same section as the dashboard that links to them. A name-derived fallback puts them in a
+   * group that dashboard is not in, and nothing fails.
+   */
+  section?: string
+  /** True when the design adopted a file that already existed rather than naming a new one. */
+  adopted: boolean
+  specs: { ux: string, ui: string }
+  /** Keys into `components`, in render order. */
+  components: string[]
+}
+
+export interface StoryDesignComponent {
+  name: string
+  definition: string
+  path: string
+  viewModelPath: string
+  adopted: boolean
+  /** The screen this component is rendered into. */
+  screen: string
+  entities: string[]
+  specs: { ux: string, ui: string }
+  // `outcome` is deliberately ABSENT. Where a successful submit returns the actor is read per call
+  // from the live registry, because the registry gains this story's own screens as the run goes;
+  // a value decided at design time returns the user to a placeholder.
+}
+
+export interface StoryDesignType {
+  path: string
+  entity: string
+  purpose: string
+  /** Which components need it — what makes the flat list re-groupable per entity. */
+  components: string[]
+}
+
+export interface StoryDesignResource {
+  path: string
+  entity: string
+  type: string
+  alias: string
+  purpose: string
+}
+
+export interface StoryDesignModel {
+  path: string
+  entities: string[]
+  /**
+   * WRITE-BACK slot, filled by the implementation stage.
+   *
+   * `designSolution`'s only honest input is the type and resource CODE, which does not exist until
+   * implementation has written it. Designing it earlier means designing it blind — against paths
+   * with no content behind them — and the fixer then spends its budget on an API the coder never
+   * saw declared. So it is designed late and recorded here, where a re-implementation reads it
+   * back instead of paying for it again.
+   */
+  solution?: string
+}
+
+export interface StoryDesignEndpoint {
+  alias: string
+  method: string
+  path: string
+  purpose: string
+}
+
+export interface StoryDesignApi {
+  path: string
+  entity: string
+  type: string
+  model: string
+  endpoints: StoryDesignEndpoint[]
+}
+
+export interface StoryDesignStore {
+  path: string
+  entity: string
+  type: string
+  api: string
+}
+
+/** What the design was written against, so a reader can tell whether it still applies. */
+export interface StoryDesignProvenance {
+  designedAt: string
+  narrativeHash: string
+  /** Specification + vision + design system, hashed together. */
+  projectHash: string
+  registryHash: string
+  /**
+   * Every path the design named, with the content hash it had at the time.
+   *
+   * An ARRAY, not a map: generated paths carry dots and slashes, and a Mongo key cannot hold them.
+   * Advisory in any case — implementation ALWAYS re-reads a path and branches on what is there
+   * now, so a tree that moved is a flipped branch rather than a crash.
+   */
+  paths: Array<{ path: string, hash: string }>
+}
+
+/**
+ * Everything a story WILL be, decided before any of it is written.
+ *
+ * The design stage writes no file into the target; the implementation stage writes nothing that is
+ * not named here. That split is what makes a story re-implementable without re-designing it — and
+ * what makes a design reviewable, amendable and reusable at all.
+ */
+export interface StoryDesign {
+  version: number
+  code: string
+  narrative: string
+  area: ProjectArea
+  /**
+   * What the scaffold reserved when it drew the application.
+   *
+   * Read once, at the first design step, and copied in. Implementation never re-reads the story
+   * file: one reader, one moment, one answer — otherwise a re-develop can drift out of the menu
+   * group its own dashboard sits in.
+   */
+  reserved: { section?: string, screen?: string }
+  entities: Array<{ name: string, description: string, dir: string }>
+  screens: StoryDesignScreen[]
+  components: StoryDesignComponent[]
+  types: StoryDesignType[]
+  resources: StoryDesignResource[]
+  models: StoryDesignModel[]
+  api: StoryDesignApi[]
+  stores: StoryDesignStore[]
+  transitions: UXTransition[]
+  /**
+   * WRITE-BACK slot, filled by the implementation stage.
+   *
+   * The design cannot even claim the KEYS: `describeApiAccess` reads the generated alias tree and
+   * the model answers with the alias strings as written there. What is designed early is the set
+   * of endpoints and screens; what they are guarded by is decided against the code that exists.
+   */
+  access: { list: AccessList, resolvedAt: Record<string, string> }
+  /**
+   * What this story needs beyond a screen, an endpoint and a table.
+   *
+   * Optional, and read through {@link runtimeOf} everywhere: a design written before the gate
+   * existed carries none, and "none" is both the safe reading and the true one.
+   */
+  runtime?: StoryDesignRuntime
+  provenance: StoryDesignProvenance
+}
+
+/** What a caller hands the store; the revision is the store's to allocate. */
+export interface StoryDesignInput {
+  projectId: string
+  storyId?: string
+  code: string
+  kind: string
+  payload: unknown
+  runId?: string
+}
+
+/**
+ * How the implementation stage reaches the design, without knowing where it lives.
+ *
+ * A port rather than a resource for the usual reason: two questions is the whole of what an
+ * implementation step needs, and a port that small is satisfiable by a record store, a file, or a
+ * test double.
+ */
+export interface StoryDesignPort {
+  current: (projectId: string, code: string) => Promise<{ revision: number, design: StoryDesign } | null>
+  put: (input: StoryDesignInput) => Promise<number>
+}

package/src/dev/consts.ts

@@ -0,0 +1,35 @@
+
+export enum AccessLevel {
+  Guest = 'guest',
+  User = 'user',
+  Permissioned = 'permissioned',
+  /**
+   * The project owner. Authenticated and holding the admin marker, which passes every gate —
+   * so this level names a marker, never a list of the project's own permissions.
+   */
+  Admin = 'admin',
+}
+
+/**
+ * Alias prefixes of the entrypoints a generated project declares.
+ *
+ * Everything a target app addresses — a screen or an endpoint — is an entrypoint referenced by
+ * alias, and the prefix says which side owns it. The pipeline splits access rules by this prefix
+ * alone, so it is load-bearing, not decorative.
+ *
+ * The split is one-sided on purpose: an alias starting with {@link ALIAS_PREFIX_API} is an API
+ * entrypoint, and ANYTHING ELSE is a screen. The framework contributes screen aliases of its own
+ * (`base`, `home`, `dispatcher`) that carry no prefix at all, so testing for
+ * {@link ALIAS_PREFIX_WEB} would silently drop them.
+ */
+export const ALIAS_PREFIX_API = 'api:'
+
+/** The prefix every GENERATED screen alias carries — see {@link ALIAS_PREFIX_API} for the split. */
+export const ALIAS_PREFIX_WEB = 'web:'
+
+/**
+ * The prefix of a LAYOUT entrypoint — the parent a screen hangs under so the layout wraps it.
+ * A layout 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.
+ */
+export const ALIAS_PREFIX_WEB_LAYOUT = 'web:layout:'

package/src/dev/index.ts

@@ -0,0 +1,4 @@
+
+export * from './schemas.js'
+export * from './consts.js'
+export type * from './types.js'