@abloatai/ablo 0.37.0 → 0.37.1

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +73 -90
  2. package/README.md +54 -26
  3. package/package.json +3 -3
package/CHANGELOG.md CHANGED
@@ -1,96 +1,79 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.37.1
4
+
5
+ ### A clearer introduction to Ablo
6
+
7
+ The package README now explains Ablo from the problem outward: humans already
8
+ coordinate shared work by seeing who is active, agreeing on ownership, waiting,
9
+ and looking again before continuing; Ablo gives agents those same practical
10
+ capabilities in software.
11
+
12
+ It also makes the headless product explicit. The TypeScript SDK is backed by a
13
+ pure HTTP transaction API, so agents, services, jobs, command-line tools, and
14
+ interactive applications can use the same coordination model without requiring
15
+ a browser or reactive client.
16
+
17
+ ### Lower overhead on busy write paths
18
+
19
+ Large create batches now return only the inserted identifiers needed for
20
+ idempotency handling instead of sending every inserted column back to the
21
+ server. Live clients also bypass reconciliation work when a publication frame
22
+ contains one change per entity.
23
+
24
+ These changes reduce server response volume and client materialization work.
25
+ There are no public API changes in 0.37.1.
26
+
3
27
  ## 0.37.0
4
28
 
5
- ### Minor Changes
6
-
7
- - f60ed16: Harden browser authentication around one typed credential endpoint contract,
8
- full-plane persistence isolation, awaited terminal cleanup, actual credential
9
- expiry, and least-privilege human sessions.
10
-
11
- Human session minting now requires a non-empty schema-typed `can` grant. It
12
- accepts concrete model operations and has no all-data wildcard. Browser
13
- credentials remain short-lived, refreshable, and isolated from long-lived
14
- server secrets.
15
-
16
- Endpoint URLs move from `apiKey` to `authEndpoint`. The canonical session and
17
- capability mint routes are `/v1/ephemeral_keys` and `/v1/capabilities`; legacy
18
- route aliases are removed.
19
-
20
- Credential providers now use the `CredentialProvider` type. The former
21
- `ApiKeySetter` export is removed.
22
-
23
- - 16cc7d1: Claims are field-granular. The `path` and `range` claim targets are removed, and
24
- a claim narrows to a whole field or set of fields and no finer. Two agents on the
25
- same row proceed concurrently when they hold different fields, and serialize when
26
- they share one.
27
-
28
- This is a breaking removal (the `path` and `range` claim options, the
29
- `TargetRange` type, and sub-field conflict semantics are gone) and a deliberate
30
- one. A claim must not promise finer exclusion than the write path can deliver,
31
- and the smallest thing a write addresses is a whole field: nothing writes part of
32
- a value. `path`/`range` let two writers hold disjoint spans of one field and told
33
- them it was safe, which it is not until concurrent edits to one field can be
34
- reconciled (operational transformation). Until that lands, field is the floor;
35
- when it lands, sub-field targets return, working.
36
-
37
- If you narrowed a claim by `path` or `range`, claim the field the position lives
38
- in instead: `fields: ['content']`. To describe a sub-field region to peers for
39
- display, put it in `meta` — that promises nothing about exclusion.
40
-
41
- - 08a3cad: Launch the branded Ablo package as the single package application developers
42
- install. The root serves headless HTTP callers, while `/client` and `/react`
43
- serve WebSocket-backed reactive applications.
44
-
45
- The public surface now provides:
46
-
47
- - `@abloatai/ablo` for agents, services, workers, jobs, and backend code;
48
- - `@abloatai/ablo/client` for live local state;
49
- - `@abloatai/ablo/react` for React bindings;
50
- - branded schema, source-adapter, server, authorization, coordination, and wire
51
- subpaths; and
52
- - `/source/next`, `/source/drizzle`, `/source/kysely`, and
53
- `/source/conformance` for Data Source integrations.
54
-
55
- Authoritative reads use `model.get({ id })`; reactive snapshots use
56
- `model.local.get(id)`.
57
-
58
- Ablo is now presented as the transaction and coordination API for state
59
- operated by humans, services, tools, and AI agents. Realtime synchronization
60
- remains available as a client capability rather than defining the product.
61
- Live applications no longer accept HTTP transport configuration, and the old
62
- sync-engine package and compatibility paths are removed.
63
-
64
- The public repository preserves the workspace structure used for development
65
- instead of flattening sources into a generated package. The branded banner,
66
- documentation, examples, license, notices, and release automation remain part
67
- of the repository.
68
-
69
- The new package pages direct application developers to the branded Ablo
70
- entrypoints while still documenting where integration authors can find the
71
- lower-level transaction and interactive-client contracts.
72
-
73
- - f60ed16: Improve confirmed commit throughput and live-client materialization without
74
- weakening atomic writes, ordered observation, audit delivery, or replay.
75
-
76
- The certified AWS benchmark sustained more than 10,000 committed operations per
77
- second for homogeneous creates, mixed creates, updates, and deletes with zero
78
- write errors and sub-second publication drain. The result covers the documented
79
- single-plane, 12-client, 500-operation benchmark topology rather than claiming
80
- universal production capacity.
81
-
82
- Live clients now defer reactive model activation until state reaches a
83
- consumer-visible boundary and keep cache eviction work bounded under sustained
84
- ingestion. Optimistic state and actively observed models remain immediately
85
- reactive.
86
-
87
- ### Patch Changes
88
-
89
- - Updated dependencies [f60ed16]
90
- - Updated dependencies [16cc7d1]
91
- - Updated dependencies [08a3cad]
92
- - Updated dependencies [f60ed16]
93
- - @abloatai/transaction@0.37.0
94
- - @abloatai/humans@0.37.0
29
+ ### One Ablo SDK for humans, agents, and backend systems
30
+
31
+ Ablo is now presented and shipped as the transaction and coordination layer for
32
+ shared application state—not only as a realtime synchronization library.
33
+
34
+ Install `@abloatai/ablo` as the single public SDK:
35
+
36
+ - `@abloatai/ablo` provides the pure HTTP path for agents, services, workers,
37
+ jobs, server actions, and other headless runtimes.
38
+ - `@abloatai/ablo/client` adds live local state, optimistic interaction,
39
+ persistence, and presence for human-facing applications.
40
+ - `@abloatai/ablo/react` provides the React bindings.
41
+
42
+ Every entrypoint uses the same schema, capabilities, commits, claims,
43
+ idempotency, settlement, and ordered changes. Authoritative reads use
44
+ `model.get({ id })`; local reactive snapshots use `model.local.get(id)`.
45
+
46
+ ### Coordination now matches the unit applications can safely write
47
+
48
+ Claims can coordinate an entire row or a typed set of fields. Two actors
49
+ working on different fields of the same row can proceed concurrently, while
50
+ overlapping work takes turns.
51
+
52
+ Sub-field `path` and `range` claims have been removed because the write path
53
+ cannot yet guarantee independent updates within one field. Applications using
54
+ those options should claim the containing field instead and keep any
55
+ cursor/range information in claim metadata for display.
56
+
57
+ ### Safer authority for browser applications
58
+
59
+ Browser sessions now use one typed, short-lived credential flow and require a
60
+ non-empty schema-typed `can` grant. Applications specify the exact model
61
+ operations a session may perform instead of issuing ambient all-data access.
62
+
63
+ Use `authEndpoint` for the browser credential endpoint. The supported routes
64
+ are `/v1/ephemeral_keys` and `/v1/capabilities`; the former `apiKey` endpoint
65
+ option and legacy route aliases are removed. Credential callbacks now use the
66
+ `CredentialProvider` type.
67
+
68
+ ### Verified throughput without dropping coordination guarantees
69
+
70
+ The strict AWS benchmark sustained more than 10,000 committed operations per
71
+ second across create, mixed-create, update, and delete workloads, with zero
72
+ write errors and sub-second publication drain.
73
+
74
+ The result covers the documented single-plane, 12-client, 500-operation test
75
+ topology. Atomic commits, authorization, idempotency, conflict handling, audit
76
+ delivery, ordered observation, replay, and authoritative confirmation remained
77
+ enabled throughout the run.
95
78
 
96
79
  Release notes are generated from the repository changesets.
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  </p>
4
4
 
5
5
  <p align="center">
6
- <strong>Transaction and coordination infrastructure for humans, agents, and backend systems.</strong>
6
+ <strong>Coordination infrastructure for humans, agents, and backend systems.</strong>
7
7
  </p>
8
8
 
9
9
  <p align="center">
@@ -22,45 +22,73 @@
22
22
 
23
23
  ---
24
24
 
25
- Install the public SDK:
25
+ Ablo is a TypeScript framework and API for applications where AI agents,
26
+ people, and backend services work on the same data. It provides typed reads and
27
+ writes, claims, safe retries, authoritative confirmation, live updates, and
28
+ attribution while your Postgres remains the source of truth.
26
29
 
27
- ```sh
28
- npm install @abloatai/ablo
29
- ```
30
+ The SDK is backed by a pure HTTP transaction API, so Ablo works in agents,
31
+ servers, jobs, command-line tools, and interactive applications without
32
+ requiring a browser or reactive client.
33
+
34
+ ## Why Ablo
30
35
 
31
- Use the root package for headless agents, services, jobs, and backend code:
36
+ Humans coordinate shared work naturally. We see that somebody is editing,
37
+ agree on who takes which part, wait our turn, and look again before continuing.
38
+
39
+ Agents do not have that awareness. Two agents can read the same row, think for
40
+ thirty seconds, and overwrite each other. An agent can act on information that
41
+ changed while it was reasoning without causing a database conflict at all.
42
+
43
+ Ablo gives agents the same practical capabilities humans rely on: see who is
44
+ working, claim a row or field, wait fairly, receive fresh state, prove what
45
+ they may do, and leave an attributed record. Humans and backend services use
46
+ the same rules, so there is no separate agent write path.
32
47
 
33
48
  ```ts
34
- import { Ablo } from '@abloatai/ablo';
49
+ await using claim = await ablo.orders.claim({ id: orderId });
50
+
51
+ const priced = await pricingAgent(claim.data);
35
52
 
36
- const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
37
53
  await ablo.orders.update({
38
54
  id: orderId,
39
- data: { status: 'approved' },
55
+ data: { total: priced.total, status: 'repriced' },
56
+ claim,
57
+ wait: 'confirmed',
40
58
  });
41
59
  ```
42
60
 
43
- Use the client entrypoint for a WebSocket-backed reactive application:
61
+ The claim releases automatically. Overlapping work takes turns, stale work is
62
+ rejected, retries are safe, and `confirmed` means the authoritative database
63
+ reported the change back.
44
64
 
45
- ```ts
46
- import { Ablo } from '@abloatai/ablo/client';
65
+ ## Start
47
66
 
48
- const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
49
- await ablo.ready();
67
+ ```sh
68
+ npm install @abloatai/ablo
69
+ npx ablo init
70
+ npx ablo push
50
71
  ```
51
72
 
52
- React bindings are available from `@abloatai/ablo/react`.
73
+ Use `@abloatai/ablo` for agents and backend code,
74
+ `@abloatai/ablo/client` for live applications, and
75
+ `@abloatai/ablo/react` for React. All entrypoints share the same schema,
76
+ authority, commits, claims, and ordered changes.
53
77
 
54
- The repository keeps implementation ownership explicit:
78
+ Read the [Quickstart](./docs/quickstart.md), browse
79
+ [docs.abloatai.com](https://docs.abloatai.com), or run `npx ablo docs`.
80
+ Coding agents can read `node_modules/@abloatai/ablo/llms.txt`.
55
81
 
56
- ```text
57
- packages/ablo branded SDK users install
58
- packages/transaction HTTP, contracts, commits, claims, settlement, observation
59
- packages/humans WebSocket, local materialization, presence, MobX, React
60
- packages/agent agent behavior and perception
61
- packages/cli project and operational tooling
62
- ```
82
+ ## Contributing
83
+
84
+ Ablo is free and open source. You can help by
85
+ [opening an issue](https://github.com/Abloatai/ablo/issues),
86
+ [suggesting a feature](https://github.com/Abloatai/ablo/issues/new), or
87
+ [contributing code](https://github.com/Abloatai/ablo/pulls).
88
+
89
+ Please report vulnerabilities privately through
90
+ [GitHub Security Advisories](https://github.com/Abloatai/ablo/security/advisories/new).
91
+
92
+ ## License
63
93
 
64
- Realtime synchronization is a consumer of the transaction layer, not a second
65
- authority path. Humans, agents, and backend services use the same commit,
66
- idempotency, claim, fencing, settlement, and ordered-observation contracts.
94
+ Apache License 2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@abloatai/ablo",
3
- "version": "0.37.0",
3
+ "version": "0.37.1",
4
4
  "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -114,8 +114,8 @@
114
114
  "directory": "packages/ablo"
115
115
  },
116
116
  "dependencies": {
117
- "@abloatai/humans": "^0.37.0",
118
- "@abloatai/transaction": "^0.37.0"
117
+ "@abloatai/humans": "^0.37.1",
118
+ "@abloatai/transaction": "^0.37.1"
119
119
  },
120
120
  "peerDependencies": {
121
121
  "react": "^19.2.8"