starci-harness 1.1.0-alpha.76 → 1.1.0-alpha.78

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -29,6 +29,8 @@ Migrations run only through `cli migrate run` (in lite it delegates to the manag
29
29
  migration runner of `platform/database`), before api processes start. Api apps never migrate or seed; seeding is a
30
30
  `cli seed ...` command.
31
31
 
32
+ DDL text is written in migrations. The one exception is a DDL renderer an app declares in hfs.json `sides.be.ddlRenderers` (`{ path, reason }`, a file of a root package such as `packages/agent-sdk/src/entity/render*.ts`): it builds and returns DDL text, the cli (`cli entities plan --write`) writes it as a new migration file, and nothing executes it at run time. In that file a database client import and a `.query/.execute/.raw/.unsafe` call are refused, and a file outside the cli and the root packages that imports a symbol the renderer declares, directly or through a package barrel, is refused.
33
+
32
34
  Why: two processes racing to migrate corrupt a schema, and a migration inside a serving module cannot be retried alone.
33
35
 
34
36
  Enforced by: `no-runtime-schema` (R34), R147.
@@ -56,6 +58,14 @@ required, and the registry is imported only by the files its slot's `importedBy`
56
58
  exports it, because database.module, the entity list and the capability barrels would form a cycle that fails at boot
57
59
  (`InjectPrimaryEntityManager is not a function`).
58
60
 
61
+ An engine-owned data model is the one exception to an entity file per table. When hfs.json `sides.be.engineOwned` declares
62
+ `{ capability, tables, partitionsOf, views, manifest }`, that one capability owns the listed base tables (for example `records`,
63
+ `record_links`, `entity_sequences`), every partition `<partitionsOf>_<entity>` and every view matching `views` (`v_*`), all built by
64
+ generated migrations. They need no `*.entity.ts` per partition or view: TypeScript reaches them through the engine's own
65
+ `EntitySchema`s (the base tables) and its generated typed views, and `starci app db drift` (R333) compares the partitions, views,
66
+ CHECKs and indexes with the entity manifest the engine generates (`manifest`, relative to the app root). Any other capability that
67
+ maps one of these objects with an `@Entity` (R35), or writes or reads one in SQL (R86), is refused.
68
+
59
69
  Why: one owner per table gives every schema change one reviewer and keeps platform free of domain types; the one
60
70
  registry that names every list is the only place that knowledge meets.
61
71
 
@@ -245,13 +255,16 @@ Enforced by: R214, R255 (hfs checks over the migrations).
245
255
 
246
256
  ## BE-PERSISTENCE-19 Lite: policies, definers and configuration keep the boundary
247
257
 
248
- A browser-role policy proves a principal predicate (`auth.uid()`), never a constant or `IS NOT NULL`. An exposed view is
258
+ A policy for any role but the trusted application role proves a principal predicate (`auth.uid()`, `auth.jwt()`, the request JWT claims, or a transaction setting the app declares in hfs.json `db.scopeSettings`, read directly with `current_setting` or through a SQL function whose body reads it, as an engine role entered per transaction does), a declared setting counts only in a policy whose roles are all declared scope roles (hfs.json `db.scopeRoles`, each `{ role, reason }`, created NOLOGIN NOINHERIT NOBYPASSRLS by a migration and granted only to the application role; R255 `DB_APP_ROLE`), only as `<owning column> = <setting or its function>` (hfs.json `db.scopeColumns`, default `workspace_id`), and never a constant, `IS NOT NULL`, `OR true`, a self comparison or a setting not declared. An exposed view is
249
259
  `security_invoker`; a `SECURITY DEFINER` function pins `search_path` and revokes EXECUTE from public and the browser
250
260
  roles. Extensions follow `ruleParams.db.extensions`; migrations write no secret or role password; destructive DDL lives
251
261
  only in a `*_contract_*` migration after the code stops using the target, or in the exact objects of one migration that an owner
252
262
  ruling in hfs.json `db.destructiveRulings` names, accepted only while the same proof finds them unreferenced. A migration already
253
263
  on the base unchanged is immutable, so its destructive or dynamic DDL is a known item: a fix is a new migration. An archived
254
- migration chain keeps one baseline and is never edited.
264
+ migration chain keeps one baseline and is never edited. The one exception is an owner-ruled one-time reset an app declares in hfs.json
265
+ `db.baselineReset` (`{ baseline, ruling, date, reason }`): the declared baseline file (header `-- starci:baseline-reset <ruling>`) replaces the whole
266
+ older chain and the archive while it is not yet on the base branch; exactly one file carries the marker, no older file stays, and once it
267
+ is on the base the declaration is spent.
255
268
 
256
269
  Why: a view, definer or configuration change can expose rows while the base table looks protected.
257
270
 
@@ -105,7 +105,7 @@ provider and hooks over its own client (a provider draws nothing). It owns no vi
105
105
  or world lifecycle, and no component built from anything but the grammar's. A workbench package (the `src/workbench/`
106
106
  and `src/public/` subpaths of a root module package, [project/README.md](../../project/README.md) PROJECT-3) draws its
107
107
  screens with grammar components alone, and the front-end canon and the grammar lint judge those subpaths from the
108
- app root's managed `eslint.config.mjs` with the rules of the front end; a visual two apps share belongs to the grammar.
108
+ app root's managed `eslint.config.mjs` with the rules of the front end, and so is every other `.tsx` file of a root package source (a `src/client/` renderer); a visual two apps share belongs to the grammar.
109
109
 
110
110
  Why: a second visual owner beside the grammar is a fork of the design system, and drawing with the grammar's own parts
111
111
  adds none.
@@ -400,9 +400,9 @@ roles:
400
400
 
401
401
  - id: data-views
402
402
  ui: ui/components/data-views.md
403
- renderers: [Board, ScheduleGrid, BarChart]
403
+ renderers: [Board, ScheduleGrid, BarChart, ProportionBar]
404
404
  vendorParity: [] # no HeroUI part: Common regions built from the card, the table and the scroll region
405
- slots: ["Board: label, columns (id, title, count, items as list rows, empty)", "ScheduleGrid: label, columns, rows, items placed by row and column (title, meta, tone, onPress), cellLabels, empty", "BarChart: label, bars (id, label, value, valueLabel), empty", "every view: isLoading, error (message, description, actionLabel, onAction)"]
405
+ slots: ["Board: label, columns (id, title, count, items as list rows, empty)", "ScheduleGrid: label, columns, rows, items placed by row and column (title, meta, tone, onPress), cellLabels, empty", "BarChart: label, bars (id, label, value, valueLabel), empty", "ProportionBar: label, parts (id, label, value, valueLabel, tone), empty", "every view: isLoading, error (message, description, actionLabel, onAction)"]
406
406
  variants:
407
407
  tone: { values: [neutral, accent, success, warning, danger], chosenBy: app from the entry's state (ScheduleGrid items) }
408
408
  sizes: none
@@ -313,14 +313,14 @@ rules:
313
313
  - {kind: eslint-be, id: entrypoint-only-in-apps}
314
314
  - id: R34
315
315
  code: BE_SCHEMA_AUTHORITY
316
- law: Migrations own the application schema and run only through the cli migrate command or the test world, and `synchronize` is false.
316
+ law: "Migrations own the application schema and run only through the cli migrate command or the test world, and `synchronize` is false. One declared exception: a root-package file hfs.json `sides.be.ddlRenderers` lists (the renderer `cli entities plan --write` uses to write NEW migration files) may hold DDL text only to build and return it; it never imports a database client or calls `.query/.execute`, and no file outside the cli and the root packages imports a symbol it declares."
317
317
  failureCodes:
318
318
  - BE_SCHEMA_AUTHORITY
319
319
  enforcers:
320
320
  - {kind: eslint-be, id: no-runtime-schema}
321
321
  - id: R35
322
322
  code: BE_SCHEMA_OWNER
323
- law: Entities and migrations live in the owning capability's `persistence/` and register under exactly one declared connection, except platform capabilities the manifest lists as `perConnection`; in lite a capability's `persistence/entities/index.ts` declares its `<c>Entities` and `platform/database/entities.ts` names it in `PRIMARY_ENTITIES`.
323
+ law: Entities and migrations live in the owning capability's `persistence/` and register under exactly one declared connection, except platform capabilities the manifest lists as `perConnection`; in lite a capability's `persistence/entities/index.ts` declares its `<c>Entities` and `platform/database/entities.ts` names it in `PRIMARY_ENTITIES`. The engine-owned objects of hfs.json sides.be.engineOwned (the base tables, the partitions of one of them and its views, built by generated migrations) need no entity per table and are mapped by the declared capability alone.
324
324
  failureCodes:
325
325
  - BE_SCHEMA_OWNER
326
326
  enforcers:
@@ -830,7 +830,7 @@ rules:
830
830
  - {kind: eslint-be, id: injection-token-exported}
831
831
  - id: R86
832
832
  code: BE_SQL_TABLE_OWNER
833
- law: SQL writes only its own capability's tables, reads only tables of its own context, and bounds every multi-row SELECT.
833
+ law: SQL writes only its own capability's tables, reads only tables of its own context, and bounds every multi-row SELECT. The engine-owned objects of hfs.json sides.be.engineOwned belong to the declared engine capability alone.
834
834
  failureCodes:
835
835
  - BE_SQL_TABLE_OWNER
836
836
  enforcers:
@@ -1500,7 +1500,7 @@ rules:
1500
1500
  - {kind: hfs, id: lite-brand-work}
1501
1501
  - id: R213
1502
1502
  code: DB_MIGRATION_SHAPE
1503
- law: A migration is `db/migrations/<ts14>_<kebab>.sql` with a valid unique stamp sorting after the committed active migrations, parses as PostgreSQL, carries no transaction control (it is applied in one transaction with its history row), and is immutable once on the base.
1503
+ law: "A migration is `db/migrations/<ts14>_<kebab>.sql` with a valid unique stamp sorting after the committed active migrations, parses as PostgreSQL, carries no transaction control (it is applied in one transaction with its history row), and is immutable once on the base. A declared one-time baseline reset (hfs.json `db.baselineReset` = `{ baseline, ruling, date, reason }`, the owner ruling for an app that keeps no data worth migrating) makes the one declared baseline file (`-- starci:baseline-reset <ruling>` header) the new base chain while it is not yet on the base branch: the removal of every older active file and of the archive is accepted (R213 immutability, R257 archive immutability); exactly one file may carry the marker, no older active file may stay, and later migrations sort after the baseline. Once the baseline is on the base branch the declaration is spent and every rule applies to it unchanged; without the declaration nothing changes."
1504
1504
  failureCodes:
1505
1505
  - DB_MIGRATION_SHAPE
1506
1506
  enforcers:
@@ -1653,7 +1653,7 @@ rules:
1653
1653
  - {kind: hfs, id: db-app-role}
1654
1654
  - id: R256
1655
1655
  code: DB_POLICY_TAUTOLOGY
1656
- law: "Exposed database objects keep their access boundaries: no tautological policies, principal-scoped browser policies, invoker-secured views and revoked execute on exposed definers."
1656
+ law: "Exposed database objects keep their access boundaries: no tautological policies, principal-scoped policies for every role but the application role (the principal is auth.uid, auth.jwt, the request JWT claims or a transaction setting the app declares in hfs.json db.scopeSettings, read only by policies whose roles are all declared in db.scopeRoles, compared with the owning column of db.scopeColumns; a scope role is granted only to the application role), invoker-secured views and revoked execute on exposed definers."
1657
1657
  editions: [lite]
1658
1658
  failureCodes:
1659
1659
  - DB_POLICY_TAUTOLOGY
@@ -2250,7 +2250,7 @@ rules:
2250
2250
  - {kind: hfs, id: lite-db-path}
2251
2251
  - id: R333
2252
2252
  code: BE_ENTITY_SCHEMA_DRIFT
2253
- law: Every TypeORM entity column of a lite app's entity list matches the schema its `db/migrations` build; `starci app db drift` applies `db/bootstrap.sql` and every migration to an empty database and compares each column.
2253
+ law: Every TypeORM entity column of a lite app's entity list matches the schema its `db/migrations` build; `starci app db drift` applies `db/bootstrap.sql` and every migration to an empty database and compares each column; an app that declares sides.be.engineOwned also has the partitions, views, CHECKs and indexes of the engine-owned objects compared with the engine's entity manifest, both ways.
2254
2254
  editions: [lite]
2255
2255
  failureCodes:
2256
2256
  - BE_ENTITY_SCHEMA_DRIFT
@@ -64,7 +64,7 @@ reads this index instead of the whole tree, then opens only the files its tasks
64
64
  - sections: BE-MESSAGES-1 One keyed bundle per owner, read through MessageCatalog · BE-MESSAGES-2 The locale is the receiver's, resolved once
65
65
  - [code/be/naming.md](../code/be/naming.md) · 4 KB — What a back-end file, class, constant, method and type is called, so the reader and the slot check know where a unit belongs from its name.
66
66
  - sections: BE-NAMING-1 Files are kebab-case with a role suffix from the closed list · BE-NAMING-2 Classes are the subject plus the role · BE-NAMING-5 Tokens, injectors and connection names have one form · BE-NAMING-6 Methods say what they promise · BE-NAMING-7 Type names carry their layer · BE-NAMING-8 GraphQL fields are camelCase operation names
67
- - [code/be/persistence.md](../code/be/persistence.md) · 19 KB — Who owns a table, how its schema changes, how the database is reached and how transactions are drawn.
67
+ - [code/be/persistence.md](../code/be/persistence.md) · 22 KB — Who owns a table, how its schema changes, how the database is reached and how transactions are drawn.
68
68
  - sections: BE-PERSISTENCE-1 Migrations are the only schema authority · BE-PERSISTENCE-2 The cli applies migrations; serving apps never do · BE-PERSISTENCE-3 Entities belong to the capability that owns the table · BE-PERSISTENCE-4 Lite holds no SQL text: entities or `callDbFunction`; full SQL is a `sql`-tagged constant · BE-PERSISTENCE-5 Work that must follow a write is written in the same transaction · BE-PERSISTENCE-6 No transaction spans an external call · BE-PERSISTENCE-7 The database is reached through the named shared EntityManager · BE-PERSISTENCE-8 One database is one connection and one injector · BE-PERSISTENCE-9 A capability touches only its own tables, and every list is bounded · BE-PERSISTENCE-10 The domain service opens the transaction and hands the manager down · BE-PERSISTENCE-11 Full: a connection is a bounded context, coupled to others only by events · BE-PERSISTENCE-16 An UPDATE or DELETE with RETURNING is wrapped in a SELECT · BE-PERSISTENCE-17 Lite: product data is reached through the back end only · BE-PERSISTENCE-19 Lite: policies, definers and configuration keep the boundary
69
69
  - [code/be/projections.md](../code/be/projections.md) · 3 KB — Decides where a read that needs another context's data comes from: never a cross-context join, but a read model on the reading context's connection, recomputed from source events.
70
70
  - sections: BE-PROJECTIONS-1 Only the projection writes its table · BE-PROJECTIONS-2 A projection speaks recompute and get, and hides its entity · BE-PROJECTIONS-3 A projection publishes nothing and is kept current by a reactor or a job · BE-PROJECTIONS-4 A declared projection is proven on the test world
@@ -181,7 +181,7 @@ reads this index instead of the whole tree, then opens only the files its tasks
181
181
  - sections: One word, one meaning: "slot" · Slot fields · Rule parameters (`ruleParams`) · Rules · The harness's own shape · Editing · Rule notes
182
182
  - [hfs/harness.yaml](../hfs/harness.yaml) · 20 KB — The harness repository's own HFS: what may exist in this repository (hfs.json kind runtime) and where.
183
183
  - ids: app.package, app.tree, cli.edition-verbs, cli.entry, cli.harness, cli.package, cli.shared, cli.verb-data, cli.verbs, contexts.harness-shape, contexts.knowledge, contexts.load-order, github.actions, github.ci, github.meta, github.scripts, github.workflows, images.dockerfile, images.readme, images.runtime-layer, images.sources, never.build-output, never.cli-js, never.env and 38 more
184
- - [hfs/rules.yaml](../hfs/rules.yaml) · 129 KB — The HFS rule catalog: one entry per rule, its finding code, its law in one sentence, the failure codes it reports and the enforcers that judge it.
184
+ - [hfs/rules.yaml](../hfs/rules.yaml) · 131 KB — The HFS rule catalog: one entry per rule, its finding code, its law in one sentence, the failure codes it reports and the enforcers that judge it.
185
185
  - ids: R01, R02, R03, R04, R05, R06, R10, R100, R101, R102, R103, R104, R105, R106, R107, R108, R109, R11, R110, R111, R112, R113, R12, R13 and 274 more
186
186
  - [hfs/slots.yaml](../hfs/slots.yaml) · 109 KB — The HFS slot manifest: what may exist in an app repository and where.
187
187
  - ids: app.agent-output, app.browser, app.browser-config, app.build-output, app.ci, app.ci-authorize-deploy-key, app.ci-cache-verify, app.ci-db, app.ci-deploy, app.ci-e2e, app.ci-images, app.ci-stack-deploy, app.ci-stack-key-restore, app.db, app.db.bootstrap, app.db.image, app.db.migrations, app.db.migrations.archive, app.declaration, app.dependabot, app.deploy, app.dockerignore, app.format-config, app.git-meta and 140 more
@@ -17,19 +17,19 @@ pins:
17
17
  '@starci/auth': {version: 0.4.0, group: starci, side: both, install: registry, why: "the lite sign-in: server module, front-end client, contracts and test doubles; the only importer of the identity libraries"}
18
18
  '@starci/mail': {version: 0.1.0, group: starci, side: be, install: registry, why: "outgoing mail of a back end: the Mailer port over SMTP with timeouts, required STARTTLS, attachments, a shared SMTP target policy, coded errors, typed render helpers; the only importer of nodemailer"}
19
19
  '@starci/auth-oidc': {version: 0.1.3, group: starci, side: both, install: registry, why: "the full sign-in: the OIDC client of the identity provider (Keycloak) behind the PrincipalVerifier of @starci/auth: server module, front-end client, contracts and a fake issuer; the only importer of jose in a full app"}
20
- '@starci/grammar': {version: 0.23.1, range: '~0.23.1', group: starci, side: fe, install: registry, why: "the grammar package an app composes (grammars core and offset-pop)"}
20
+ '@starci/grammar': {version: 0.23.2, range: '~0.23.2', group: starci, side: fe, install: registry, why: "the grammar package an app composes (grammars core and offset-pop)"}
21
21
  '@starci/next-i18n': {version: 0.1.0, group: starci, side: fe, install: registry, why: "the next-intl stack of a front end: defineI18n, the locale proxy, the navigation, the request config and the locale read of the [locale] layout; the app keeps its catalogs"}
22
- '@starci/eslint-canon-be': {version: 3.19.0, range: '~3.19.0', group: starci, side: be, install: registry, why: "the back-end ESLint canon"}
23
- '@starci/eslint-canon-fe': {version: 9.15.0, range: '~9.15.0', group: starci, side: fe, install: registry, why: "the universal front-end ESLint canon"}
22
+ '@starci/eslint-canon-be': {version: 3.19.1, range: '~3.19.1', group: starci, side: be, install: registry, why: "the back-end ESLint canon"}
23
+ '@starci/eslint-canon-fe': {version: 9.15.1, range: '~9.15.1', group: starci, side: fe, install: registry, why: "the universal front-end ESLint canon"}
24
24
  '@starci/eslint-grammar-core': {version: 0.23.1, range: '~0.23.1', group: starci, side: fe, install: registry, why: "the core grammar's lint factory, holding the grammar API checks every grammar inherits (open-grammar D-7); versioned with the grammar"}
25
25
  '@starci/eslint-grammar-offset-pop': {version: 0.23.1, range: '~0.23.1', group: starci, side: fe, install: registry, why: "the offset-pop grammar's lint factory; versioned with the grammar"}
26
- '@starci/stylelint-canon': {version: 2.6.0, group: starci, side: fe, install: registry, why: "the front-end stylelint canon"}
26
+ '@starci/stylelint-canon': {version: 2.7.0, group: starci, side: fe, install: registry, why: "the front-end stylelint canon"}
27
27
  '@starci/tsconfig': {version: 2.1.0, group: starci, side: both, install: registry}
28
28
  '@starci/prettier-config': {version: 1.1.0, group: starci, side: both, install: registry}
29
29
  '@starci/jest-preset': {version: 2.7.1, group: starci, side: be, install: registry, why: "the back-end Jest preset; pairs exactly with @starci/test-world"}
30
30
  '@starci/test-world': {version: 1.3.4, group: starci, side: be, install: registry, why: "the back-end e2e world; pairs exactly with @starci/jest-preset"}
31
31
  '@starci/ai-router': {version: 0.5.0, group: starci, side: be, install: registry, why: "the AI pool router module of a back end; jest-preset compiles it as ESM"}
32
- '@starci/hfs': {version: 5.13.1, group: starci, side: both, install: registry, why: "the app implementation starci-harness runs for starci app"}
32
+ '@starci/hfs': {version: 5.13.3, group: starci, side: both, install: registry, why: "the app implementation starci-harness runs for starci app"}
33
33
  '@langchain/core': {version: 1.3.1, group: framework, side: be, why: "the LangChain core of the one AI integration (contexts/code/be/ai.md)"}
34
34
  '@langchain/openai': {version: 1.8.0, group: framework, side: be, why: "ChatOpenAI and OpenAIEmbeddings of the one AI integration, pointed at the ai-router gateway"}
35
35
  typescript: {version: 5.9.3, group: tooling, side: both}
@@ -14,6 +14,7 @@ Choice `data-views.choose.view`: which view a set of items takes. The first row
14
14
  | board | the items move through named stages and the reader scans each stage | `Board`: one column per stage, each a card of rows with its count; an empty stage says so in place | `DNA-COMMON-BOARD-ONE-WIDTH` |
15
15
  | schedule | each item belongs to a time or a place on two axes (a week by hour, a month, people by day) | `ScheduleGrid`: columns and rows named, items placed by both; a phone reads it as an agenda | `DNA-COMMON-SCHEDULE-HEADINGS` |
16
16
  | bars | a handful of amounts is compared on one scale (per day, per channel) | `BarChart`: the value is real text over each bar, no axis or legend | `DNA-COMMON-BAR-CHART-ONE-SCALE` |
17
+ | proportion | the parts of one whole are told at a glance (receivables by age, a share by channel) | `ProportionBar`: one track split by share, a legend with the dot, the label and the amount as real text; no axis, no percentage | candidate |
17
18
  | list | the items have no stage, place or comparison | `Section kind="list"` or `SurfaceCard kind="list"` ([list-table](list-table.md)) | judgement |
18
19
  | figures | one to five numbers each stand alone | `SurfaceCard kind="figures"` ([card](card.md)) | judgement |
19
20
 
@@ -13,6 +13,7 @@ Choice `message-bubble.choose.side`: whose message it is. The first row that app
13
13
  | --- | --- | --- | --- |
14
14
  | mine | the reader wrote it | `side="outgoing"`: the brand fill (`--accent`) with its foreground (`--accent-foreground`), at the end side | judgement |
15
15
  | theirs | anyone else wrote it: a person, an agent, the system | `side="incoming"` (the default): the surface and its foreground, at the start side | judgement |
16
+ | agent for the reader | an agent speaks on the reader's behalf and the reader may approve it (an AI's reply) | `side="outgoing" tone="soft"`: the brand tint (`--accent-soft`) with its foreground (`--accent-soft-foreground`), at the end side; `tone` never changes an incoming bubble (owner ruling 2026-11-06: no new token) | judgement |
16
17
 
17
18
  Choice `message-bubble.choose.inline`: what a message may hold. Plain words, a link, a mention (`Text isStrong`), code and a muted line
18
19
  all inherit the bubble's foreground, so they read on either face; a link keeps its underline. Anything that is not the message's own