spatialdds 0.5.4__tar.gz → 0.7.0__tar.gz

{spatialdds-0.5.4/spatialdds.egg-info → spatialdds-0.7.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.5.4
-Summary: SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command.
+Version: 0.7.0
+Summary: SpatialDDS for programs: a client for the web binding (Appendix N), a native DDS participant, and the reference registry behind one command.
 Author: Open AR Cloud
 License: Apache-2.0
-Project-URL: Homepage, https://github.com/OpenArCloud/spatialdds-web
+Project-URL: Homepage, https://github.com/OpenArCloud/spatialdds-py
 Project-URL: Specification, https://github.com/OpenArCloud/SpatialDDS-spec
-Keywords: spatialdds,spatial,geopose,anchors,registry,openarcloud
+Keywords: spatialdds,spatial,geopose,anchors,registry,dds,cyclonedds,openarcloud
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -21,15 +21,20 @@ Provides-Extra: server
 Requires-Dist: aiohttp>=3.8; extra == "server"
 Requires-Dist: mcap>=1.1; extra == "server"
 Requires-Dist: jsonschema>=4.0; extra == "server"
+Provides-Extra: dds
+Requires-Dist: cyclonedds<12,>=11.0.1; extra == "dds"
+Requires-Dist: mcap>=1.1; extra == "dds"
+Requires-Dist: jsonschema>=4.0; extra == "dds"
 
 # spatialdds
 
-SpatialDDS over plain HTTPS and a WebSocket: a client for programs, and the
-reference registry behind one command.
+SpatialDDS for programs: a client over plain HTTPS and a WebSocket, a native
+DDS participant, and the reference registry behind one command.
 
 ```sh
 pip install spatialdds                       # the client: two dependencies
 pip install "spatialdds[server]"             # and the registry
+pip install "spatialdds[dds]"                # and a native DDS participant
 pip install "./lib/spatialdds[server]"       # from a checkout of this repo
 ```
 
@@ -39,14 +44,110 @@ package is the step after that, when a program wants native values instead of
 canonical JSON, bytes it can trust, refusals it can act on, and records it did
 not have to assemble member by member.
 
-**Implements Appendix N as of SpatialDDS-spec `9c3e1f2`.** Package versions and
-specification versions move independently; `spatialdds.SPEC_COMMIT` is the one
-that says what the wire looks like.
+**Implements Appendix N as of SpatialDDS-spec `v1.8` (`4b5652c`).** Package
+versions and specification versions move independently; `spatialdds.SPEC_TAG`
+and `spatialdds.SPEC_COMMIT` are the ones that say what the wire looks like.
 
 The source, the reference gateway, the recordings and every gate behind the
-claims on this page are at [https://github.com/OpenArCloud/spatialdds-web](https://github.com/OpenArCloud/spatialdds-web). Every code block below is executed
+claims on this page are at [https://github.com/OpenArCloud/spatialdds-py](https://github.com/OpenArCloud/spatialdds-py). Every code block below is executed
 by one of those gates on every run, against an endpoint started for it.
 
+## A native participant, over DDS
+
+The same package speaks SpatialDDS natively, beside `sd.connect`. Install the
+`[dds]` extra (it brings cyclonedds), and a participant is a plain program:
+an entity with an announce, pose updates, and a clean withdrawal on exit.
+
+<!-- native: participant -->
+```python
+import spatialdds as sd
+
+with sd.participant("bare-scene", domain=42, service_id="svc:duck",
+                    authority="registry.example") as p:
+    frame = sd.frame("map/bare-scene", convention="ENU", meters_per_unit=1.0)
+    duck = p.writer("model_entity", qos_profile="MAP_META", on_exit="withdraw")
+    pose = p.writer("model_pose", qos_profile=sd.dds.Profile(
+        "DUCK_POSE", reliability="BEST_EFFORT", durability="VOLATILE"))
+    p.announce("OTHER", coverage=sd.circle(30.2849, -97.7341, 50))
+    duck.write(sd.entity("ent:duck", frame_ref=frame, source_id="svc:duck"))
+    for i in p.loop(hz=5):
+        pose.write(sd.model_pose("ent:duck", position=(i * 0.1, 0, 0),
+                                 source_id="svc:duck"))
+        if i == 9:
+            break
+print("stopped; the duck was withdrawn on the way out")
+```
+
+```console
+stopped; the duck was withdrawn on the way out
+```
+
+Anyone on the domain sees it, through the same four events the web client's
+`subscribe()` yields:
+
+<!-- native: reader -->
+```python
+import spatialdds as sd
+
+with sd.participant("bare-scene", domain=42) as p:
+    for ev in p.reader("model_entity", qos_profile="MAP_META").events(timeout=5):
+        if isinstance(ev, sd.Sample):
+            print("Sample", ev.key, ev.data.state.name)
+        elif isinstance(ev, sd.Dispose):
+            print("Dispose", ev.key, repr(ev.reason))
+        else:
+            print(type(ev).__name__)
+```
+
+```console
+EndOfReplay
+Sample ent:duck ACTIVE
+Sample ent:duck RETIRED
+Dispose ent:duck 'the participant stopped'
+```
+
+What it asks of you, and what it will not guess:
+
+| you say | or it refuses |
+| --- | --- |
+| `scene`, and `domain` (or `SPATIALDDS_DDS_DOMAIN`) | always: there is no default scene, and DDS's domain 0 is not a choice anyone made |
+| `service_id` and `authority` | to write or announce |
+| `qos_profile` | where the §3.3.2 row names none, as `model_entity`'s and `model_pose`'s do; the refusal lists the §3.3.3 profiles that fit, or pass a `sd.dds.Profile(...)` extension |
+| `on_exit="keep"` or `"withdraw"` | on every latched, keyed writer: whether a record outlives its writer is a claim only you can make |
+| `withdraw(key, reason=...)` | with an empty reason |
+
+And what it does without being asked:
+
+- **Writers never autodispose.** A participant that crashes reaches every
+  reader as `Liveliness(alive=False)` once its lease runs out. It is never a
+  `Dispose`, which is only ever somebody's `withdraw()`: a terminal sample,
+  then the dispose, with the reason.
+- **A clean stop departs.** Each writer does what its `on_exit` said. Then the
+  announce sends its terminal sample, its dispose and a `Depart`, and every
+  writer waits for its acknowledgements.
+- **The announce is kept fresh.** `tick()`, which `loop()` calls, refreshes it
+  every `ttl_sec / 3`, and its `topics` are the writers you opened. `floor_hz=`
+  keeps a stationary publisher's records fresh too.
+- **Every sample is validated** against the published JSON Schema before it is
+  written.
+
+`Sample.data` is the typed sample (`sd.dds.types` carries every type in the
+pinned IDL). `sd.dds.to_json(sample)` is its N.1 form, produced by the gateway's
+own codec, so a native sample and a served one cannot disagree.
+
+Without the extra, `import spatialdds` is unchanged, and `sd.participant`
+raises `sd.MissingExtra` naming it. Two modules are pure Python and need
+nothing:
+
+- `sd.frames`: one copy of the ENU↔ECEF arithmetic, with composition that
+  never guesses a position;
+- `sd.Recency`: learned per-key idle thresholds for fast lanes.
+
+`sd.events` holds the four event classes both transports share; `sd.dds` is the
+layer itself. Request and reply (VPS, coverage queries) is documented as a
+convention, not built, until 1.9 settles it:
+[REQUEST-REPLY.md](https://github.com/OpenArCloud/spatialdds-py/blob/main/docs/REQUEST-REPLY.md).
+
 ## Your own registry, in one command
 
 ```sh
@@ -133,9 +234,9 @@ limits   {'max_fps': 10}
 ```
 
 Every one of those is something a service operator knows and a library cannot
-guess. [The mytown walkthrough](https://github.com/OpenArCloud/spatialdds-web/blob/main/docs/MYTOWN.md) publishes that
+guess. [The mytown walkthrough](https://github.com/OpenArCloud/spatialdds-py/blob/main/docs/MYTOWN.md) publishes that
 and prints the whole served document;
-[`gates/builders.py`](https://github.com/OpenArCloud/spatialdds-web/blob/main/gates/builders.py) rebuilds that
+[`gates/builders.py`](https://github.com/OpenArCloud/spatialdds-py/blob/main/gates/builders.py) rebuilds that
 repository's hand-authored `austin-vps` and duck records through these calls
 and compares them member by member, which is what makes "every member is
 reachable from an argument" a check rather than a claim.
@@ -147,7 +248,7 @@ and the byte count itself: a hash nobody typed is a hash a reader can trust.
 else hosts, and the hash comes from whoever has the bytes. Pass no hash and
 the reference carries no integrity claim, which costs a reader one thing:
 `fetch_asset()` raises rather than reporting a check it could not perform
-([finding 31](https://github.com/OpenArCloud/spatialdds-web/blob/main/WEB-BINDING-FINDINGS.md)).
+([finding 31](https://github.com/OpenArCloud/spatialdds-py/blob/main/WEB-BINDING-FINDINGS.md)).
 `publish_content` takes either, or a path, or bytes, or a URL.
 
 The builders are also usable on their own: `sd.service_announce`,
@@ -179,7 +280,7 @@ they never fill is **identity**: `provider_id` and `org` are yours to state,
 because a library that invented a provider id would be inventing provenance.
 
 `GeoAnchor.checksum` is required by 1.8 and specified by nobody
-(spatialdds-web finding 31). The builder fills it with the SHA-256 of the
+(spatialdds-py finding 31). The builder fills it with the SHA-256 of the
 record's own canonical JSON with `checksum` emptied -- a convention, chosen
 because a reader can recompute it from what was served. If the specification
 settles the semantics, this changes.
@@ -271,7 +372,7 @@ declared.
 <!-- bar: resolve -->
 ```python
 import json, spatialdds as sd
-ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret"); ep.publish_manifest(json.load(open("samples/duck.input.json"))["manifest"]); print(len(ep.resolve("spatialdds://demo.spatialdds.org/south-mall/content/duck").fetch_asset()), "bytes verified")
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret"); ep.publish_manifest(json.load(open("samples/duck.input.json"))["manifest"]); print(len(ep.resolve("spatialdds://demo.spatialdds.org/ut-austin-south-mall/content/duck").fetch_asset()), "bytes verified")
 ```
 
 ```console
@@ -286,7 +387,7 @@ call goes away and the bar is one line.
 
 | call | what it does |
 | --- | --- |
-| `sd.connect(base, token=None, verify_integrity=True, timeout=15.0, lifted=True, scene="default", authority=None)` | an `Endpoint`; nothing is fetched until you ask |
+| `sd.connect(base, token=None, verify_integrity=True, timeout=15.0, lifted=True, scene=None, authority=None)` | an `Endpoint`; nothing is fetched until you ask. `scene` is the lane the publish verbs write; unset, they refuse rather than guess |
 | `ep.search(geohash=None, kinds=None)` | §3.3.0 search → a list of `Hit` |
 | `ep.near(lat, lon, radius_m)` | a helper over `search`, never a second protocol |
 | `ep.resolve(uri)` | §7.5.2 resolution → `Resolved` |
@@ -313,7 +414,7 @@ call goes away and the bar is one line.
 | `sd.asset(path_or_bytes, media_type=)` / `sd.asset_ref(url, hash=, media_type=)` | an asset hashed from its bytes, or a reference to one hosted elsewhere |
 | `sd.records` | the builders, listed above |
 | `sd.lift(fqn, doc)` | the lift on its own, for JSON you already have |
-| `sd.SPEC_COMMIT`, `sd.APPENDIX_N`, `sd.__version__` | what this speaks |
+| `sd.SPEC_TAG`, `sd.SPEC_COMMIT`, `sd.APPENDIX_N`, `sd.__version__` | what this speaks |
 
 `ep.near()` picks a geohash precision whose cell covers the radius, encodes the
 centre and eight points around the query circle so the covering cells are found
@@ -346,7 +447,7 @@ One family, built from the endpoint's own N.8 problem documents — `status`,
 
 That last one is the unusual one and it is deliberate. SpatialDDS counts "a
 checksum field in the body" as a §7.5.2 integrity signal, but nothing specifies
-what such a field digests or in what form (spatialdds-web finding 31). Where a
+what such a field digests or in what form (spatialdds-py finding 31). Where a
 declared value does not parse as a SHA-256 of the asset's bytes, this library
 raises rather than reporting a check it did not perform.
 
@@ -471,12 +572,65 @@ explicitly was tried first and is what missed two paths.
 
 If your clients are not browsers, nothing here changes anything for you.
 
-## Not in 0.5.4
-
-Stated so nobody waits for them: no async API, no caching beyond ETag
-revalidation, no retry policy, no MCAP tooling beyond the journal the server
-writes, no client-side command helper, and no DDS dependency of any kind. The
-wire is HTTP and a WebSocket.
+## New in 0.7.0: a native participant, and the v1.8 tag
+
+- **The package speaks DDS natively.** `sd.participant(...)`, under the `[dds]`
+  extra, is described at the top of this page. It takes the conventions as
+  code and leaves the program a plain program.
+- **One pin, the `v1.8` tag**, for everything vendored: the schemas, the IDL,
+  the native bindings and the registry its QoS comes from.
+- **Four-segment topics.** The gateway now serves them at their well-known
+  paths, where it used to drop them.
+- **Recordings carry their disposes.** A recording's withdrawals are served
+  with their reasons.
+
+Two changes may need a line of yours:
+
+- **`sd.topic()` derives durability from a registered `qos_profile`.** It used
+  to say `TRANSIENT_LOCAL` whatever the profile was. For a templated type
+  (`model_entity`) it uses the template's name.
+- **`sd.Sample` and friends moved to `spatialdds.events`.** They are
+  re-exported where they were.
+
+The repository is now
+[spatialdds-py](https://github.com/OpenArCloud/spatialdds-py), and the package
+name is unchanged. Details are in the
+[changelog](https://github.com/OpenArCloud/spatialdds-py/blob/main/lib/spatialdds/CHANGELOG.md).
+
+## New in 0.6.0: lanes, hardening, OpenAPI
+
+One registry can now take several publishers. Each one holds a token scoped to
+the scenes it may write, issued with `python -m spatialdds.tokens` and served
+with `--tokens`. A write outside its lane is a `403` naming the scene, and
+reads stay open. Manifests can be withdrawn, and the journal records who wrote
+each entry. The REST surface is published as OpenAPI 3.1 at
+`/.well-known/spatialdds/openapi`. Every limit refuses with a problem document
+naming its number.
+
+Two changes may need a line of yours:
+
+- **Publishing needs a scene.** The client's publish verbs refuse when no
+  scene is set, where they used to write into `default`. Pass `scene=`.
+- **The demo's manifest URIs changed.** They name the scene now,
+  `…/ut-austin-south-mall/…`.
+
+The security fixes, the limits table and the details are in the
+[changelog](https://github.com/OpenArCloud/spatialdds-py/blob/main/lib/spatialdds/CHANGELOG.md).
+
+## Not in 0.7.0
+
+Stated so nobody waits for them:
+
+- no async API;
+- no caching beyond ETag revalidation;
+- no retry policy;
+- no client-side command helper;
+- no request/reply machinery in the native layer. VPS and coverage queries are
+  a documented convention until 1.9 settles their shape;
+- no C++ or other-language port.
+
+The web client still has no DDS dependency of any kind: cyclonedds arrives
+only with `[dds]`.
 
 0.4.0 added the N.6 command surface described above; 0.5.0 made it usable
 from an embedder with a live source, which is two releases for one capability

spatialdds-0.5.4/PKG-INFO → spatialdds-0.7.0/README.md

@@ -1,35 +1,12 @@
-Metadata-Version: 2.4
-Name: spatialdds
-Version: 0.5.4
-Summary: SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command.
-Author: Open AR Cloud
-License: Apache-2.0
-Project-URL: Homepage, https://github.com/OpenArCloud/spatialdds-web
-Project-URL: Specification, https://github.com/OpenArCloud/SpatialDDS-spec
-Keywords: spatialdds,spatial,geopose,anchors,registry,openarcloud
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Topic :: Scientific/Engineering :: GIS
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.25
-Requires-Dist: websockets>=12
-Provides-Extra: server
-Requires-Dist: aiohttp>=3.8; extra == "server"
-Requires-Dist: mcap>=1.1; extra == "server"
-Requires-Dist: jsonschema>=4.0; extra == "server"
-
 # spatialdds
 
-SpatialDDS over plain HTTPS and a WebSocket: a client for programs, and the
-reference registry behind one command.
+SpatialDDS for programs: a client over plain HTTPS and a WebSocket, a native
+DDS participant, and the reference registry behind one command.
 
 ```sh
 pip install spatialdds                       # the client: two dependencies
 pip install "spatialdds[server]"             # and the registry
+pip install "spatialdds[dds]"                # and a native DDS participant
 pip install "./lib/spatialdds[server]"       # from a checkout of this repo
 ```
 
@@ -39,14 +16,110 @@ package is the step after that, when a program wants native values instead of
 canonical JSON, bytes it can trust, refusals it can act on, and records it did
 not have to assemble member by member.
 
-**Implements Appendix N as of SpatialDDS-spec `9c3e1f2`.** Package versions and
-specification versions move independently; `spatialdds.SPEC_COMMIT` is the one
-that says what the wire looks like.
+**Implements Appendix N as of SpatialDDS-spec `v1.8` (`4b5652c`).** Package
+versions and specification versions move independently; `spatialdds.SPEC_TAG`
+and `spatialdds.SPEC_COMMIT` are the ones that say what the wire looks like.
 
 The source, the reference gateway, the recordings and every gate behind the
-claims on this page are at [https://github.com/OpenArCloud/spatialdds-web](https://github.com/OpenArCloud/spatialdds-web). Every code block below is executed
+claims on this page are at [https://github.com/OpenArCloud/spatialdds-py](https://github.com/OpenArCloud/spatialdds-py). Every code block below is executed
 by one of those gates on every run, against an endpoint started for it.
 
+## A native participant, over DDS
+
+The same package speaks SpatialDDS natively, beside `sd.connect`. Install the
+`[dds]` extra (it brings cyclonedds), and a participant is a plain program:
+an entity with an announce, pose updates, and a clean withdrawal on exit.
+
+<!-- native: participant -->
+```python
+import spatialdds as sd
+
+with sd.participant("bare-scene", domain=42, service_id="svc:duck",
+                    authority="registry.example") as p:
+    frame = sd.frame("map/bare-scene", convention="ENU", meters_per_unit=1.0)
+    duck = p.writer("model_entity", qos_profile="MAP_META", on_exit="withdraw")
+    pose = p.writer("model_pose", qos_profile=sd.dds.Profile(
+        "DUCK_POSE", reliability="BEST_EFFORT", durability="VOLATILE"))
+    p.announce("OTHER", coverage=sd.circle(30.2849, -97.7341, 50))
+    duck.write(sd.entity("ent:duck", frame_ref=frame, source_id="svc:duck"))
+    for i in p.loop(hz=5):
+        pose.write(sd.model_pose("ent:duck", position=(i * 0.1, 0, 0),
+                                 source_id="svc:duck"))
+        if i == 9:
+            break
+print("stopped; the duck was withdrawn on the way out")
+```
+
+```console
+stopped; the duck was withdrawn on the way out
+```
+
+Anyone on the domain sees it, through the same four events the web client's
+`subscribe()` yields:
+
+<!-- native: reader -->
+```python
+import spatialdds as sd
+
+with sd.participant("bare-scene", domain=42) as p:
+    for ev in p.reader("model_entity", qos_profile="MAP_META").events(timeout=5):
+        if isinstance(ev, sd.Sample):
+            print("Sample", ev.key, ev.data.state.name)
+        elif isinstance(ev, sd.Dispose):
+            print("Dispose", ev.key, repr(ev.reason))
+        else:
+            print(type(ev).__name__)
+```
+
+```console
+EndOfReplay
+Sample ent:duck ACTIVE
+Sample ent:duck RETIRED
+Dispose ent:duck 'the participant stopped'
+```
+
+What it asks of you, and what it will not guess:
+
+| you say | or it refuses |
+| --- | --- |
+| `scene`, and `domain` (or `SPATIALDDS_DDS_DOMAIN`) | always: there is no default scene, and DDS's domain 0 is not a choice anyone made |
+| `service_id` and `authority` | to write or announce |
+| `qos_profile` | where the §3.3.2 row names none, as `model_entity`'s and `model_pose`'s do; the refusal lists the §3.3.3 profiles that fit, or pass a `sd.dds.Profile(...)` extension |
+| `on_exit="keep"` or `"withdraw"` | on every latched, keyed writer: whether a record outlives its writer is a claim only you can make |
+| `withdraw(key, reason=...)` | with an empty reason |
+
+And what it does without being asked:
+
+- **Writers never autodispose.** A participant that crashes reaches every
+  reader as `Liveliness(alive=False)` once its lease runs out. It is never a
+  `Dispose`, which is only ever somebody's `withdraw()`: a terminal sample,
+  then the dispose, with the reason.
+- **A clean stop departs.** Each writer does what its `on_exit` said. Then the
+  announce sends its terminal sample, its dispose and a `Depart`, and every
+  writer waits for its acknowledgements.
+- **The announce is kept fresh.** `tick()`, which `loop()` calls, refreshes it
+  every `ttl_sec / 3`, and its `topics` are the writers you opened. `floor_hz=`
+  keeps a stationary publisher's records fresh too.
+- **Every sample is validated** against the published JSON Schema before it is
+  written.
+
+`Sample.data` is the typed sample (`sd.dds.types` carries every type in the
+pinned IDL). `sd.dds.to_json(sample)` is its N.1 form, produced by the gateway's
+own codec, so a native sample and a served one cannot disagree.
+
+Without the extra, `import spatialdds` is unchanged, and `sd.participant`
+raises `sd.MissingExtra` naming it. Two modules are pure Python and need
+nothing:
+
+- `sd.frames`: one copy of the ENU↔ECEF arithmetic, with composition that
+  never guesses a position;
+- `sd.Recency`: learned per-key idle thresholds for fast lanes.
+
+`sd.events` holds the four event classes both transports share; `sd.dds` is the
+layer itself. Request and reply (VPS, coverage queries) is documented as a
+convention, not built, until 1.9 settles it:
+[REQUEST-REPLY.md](https://github.com/OpenArCloud/spatialdds-py/blob/main/docs/REQUEST-REPLY.md).
+
 ## Your own registry, in one command
 
 ```sh
@@ -133,9 +206,9 @@ limits   {'max_fps': 10}
 ```
 
 Every one of those is something a service operator knows and a library cannot
-guess. [The mytown walkthrough](https://github.com/OpenArCloud/spatialdds-web/blob/main/docs/MYTOWN.md) publishes that
+guess. [The mytown walkthrough](https://github.com/OpenArCloud/spatialdds-py/blob/main/docs/MYTOWN.md) publishes that
 and prints the whole served document;
-[`gates/builders.py`](https://github.com/OpenArCloud/spatialdds-web/blob/main/gates/builders.py) rebuilds that
+[`gates/builders.py`](https://github.com/OpenArCloud/spatialdds-py/blob/main/gates/builders.py) rebuilds that
 repository's hand-authored `austin-vps` and duck records through these calls
 and compares them member by member, which is what makes "every member is
 reachable from an argument" a check rather than a claim.
@@ -147,7 +220,7 @@ and the byte count itself: a hash nobody typed is a hash a reader can trust.
 else hosts, and the hash comes from whoever has the bytes. Pass no hash and
 the reference carries no integrity claim, which costs a reader one thing:
 `fetch_asset()` raises rather than reporting a check it could not perform
-([finding 31](https://github.com/OpenArCloud/spatialdds-web/blob/main/WEB-BINDING-FINDINGS.md)).
+([finding 31](https://github.com/OpenArCloud/spatialdds-py/blob/main/WEB-BINDING-FINDINGS.md)).
 `publish_content` takes either, or a path, or bytes, or a URL.
 
 The builders are also usable on their own: `sd.service_announce`,
@@ -179,7 +252,7 @@ they never fill is **identity**: `provider_id` and `org` are yours to state,
 because a library that invented a provider id would be inventing provenance.
 
 `GeoAnchor.checksum` is required by 1.8 and specified by nobody
-(spatialdds-web finding 31). The builder fills it with the SHA-256 of the
+(spatialdds-py finding 31). The builder fills it with the SHA-256 of the
 record's own canonical JSON with `checksum` emptied -- a convention, chosen
 because a reader can recompute it from what was served. If the specification
 settles the semantics, this changes.
@@ -271,7 +344,7 @@ declared.
 <!-- bar: resolve -->
 ```python
 import json, spatialdds as sd
-ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret"); ep.publish_manifest(json.load(open("samples/duck.input.json"))["manifest"]); print(len(ep.resolve("spatialdds://demo.spatialdds.org/south-mall/content/duck").fetch_asset()), "bytes verified")
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret"); ep.publish_manifest(json.load(open("samples/duck.input.json"))["manifest"]); print(len(ep.resolve("spatialdds://demo.spatialdds.org/ut-austin-south-mall/content/duck").fetch_asset()), "bytes verified")
 ```
 
 ```console
@@ -286,7 +359,7 @@ call goes away and the bar is one line.
 
 | call | what it does |
 | --- | --- |
-| `sd.connect(base, token=None, verify_integrity=True, timeout=15.0, lifted=True, scene="default", authority=None)` | an `Endpoint`; nothing is fetched until you ask |
+| `sd.connect(base, token=None, verify_integrity=True, timeout=15.0, lifted=True, scene=None, authority=None)` | an `Endpoint`; nothing is fetched until you ask. `scene` is the lane the publish verbs write; unset, they refuse rather than guess |
 | `ep.search(geohash=None, kinds=None)` | §3.3.0 search → a list of `Hit` |
 | `ep.near(lat, lon, radius_m)` | a helper over `search`, never a second protocol |
 | `ep.resolve(uri)` | §7.5.2 resolution → `Resolved` |
@@ -313,7 +386,7 @@ call goes away and the bar is one line.
 | `sd.asset(path_or_bytes, media_type=)` / `sd.asset_ref(url, hash=, media_type=)` | an asset hashed from its bytes, or a reference to one hosted elsewhere |
 | `sd.records` | the builders, listed above |
 | `sd.lift(fqn, doc)` | the lift on its own, for JSON you already have |
-| `sd.SPEC_COMMIT`, `sd.APPENDIX_N`, `sd.__version__` | what this speaks |
+| `sd.SPEC_TAG`, `sd.SPEC_COMMIT`, `sd.APPENDIX_N`, `sd.__version__` | what this speaks |
 
 `ep.near()` picks a geohash precision whose cell covers the radius, encodes the
 centre and eight points around the query circle so the covering cells are found
@@ -346,7 +419,7 @@ One family, built from the endpoint's own N.8 problem documents — `status`,
 
 That last one is the unusual one and it is deliberate. SpatialDDS counts "a
 checksum field in the body" as a §7.5.2 integrity signal, but nothing specifies
-what such a field digests or in what form (spatialdds-web finding 31). Where a
+what such a field digests or in what form (spatialdds-py finding 31). Where a
 declared value does not parse as a SHA-256 of the asset's bytes, this library
 raises rather than reporting a check it did not perform.
 
@@ -471,12 +544,65 @@ explicitly was tried first and is what missed two paths.
 
 If your clients are not browsers, nothing here changes anything for you.
 
-## Not in 0.5.4
-
-Stated so nobody waits for them: no async API, no caching beyond ETag
-revalidation, no retry policy, no MCAP tooling beyond the journal the server
-writes, no client-side command helper, and no DDS dependency of any kind. The
-wire is HTTP and a WebSocket.
+## New in 0.7.0: a native participant, and the v1.8 tag
+
+- **The package speaks DDS natively.** `sd.participant(...)`, under the `[dds]`
+  extra, is described at the top of this page. It takes the conventions as
+  code and leaves the program a plain program.
+- **One pin, the `v1.8` tag**, for everything vendored: the schemas, the IDL,
+  the native bindings and the registry its QoS comes from.
+- **Four-segment topics.** The gateway now serves them at their well-known
+  paths, where it used to drop them.
+- **Recordings carry their disposes.** A recording's withdrawals are served
+  with their reasons.
+
+Two changes may need a line of yours:
+
+- **`sd.topic()` derives durability from a registered `qos_profile`.** It used
+  to say `TRANSIENT_LOCAL` whatever the profile was. For a templated type
+  (`model_entity`) it uses the template's name.
+- **`sd.Sample` and friends moved to `spatialdds.events`.** They are
+  re-exported where they were.
+
+The repository is now
+[spatialdds-py](https://github.com/OpenArCloud/spatialdds-py), and the package
+name is unchanged. Details are in the
+[changelog](https://github.com/OpenArCloud/spatialdds-py/blob/main/lib/spatialdds/CHANGELOG.md).
+
+## New in 0.6.0: lanes, hardening, OpenAPI
+
+One registry can now take several publishers. Each one holds a token scoped to
+the scenes it may write, issued with `python -m spatialdds.tokens` and served
+with `--tokens`. A write outside its lane is a `403` naming the scene, and
+reads stay open. Manifests can be withdrawn, and the journal records who wrote
+each entry. The REST surface is published as OpenAPI 3.1 at
+`/.well-known/spatialdds/openapi`. Every limit refuses with a problem document
+naming its number.
+
+Two changes may need a line of yours:
+
+- **Publishing needs a scene.** The client's publish verbs refuse when no
+  scene is set, where they used to write into `default`. Pass `scene=`.
+- **The demo's manifest URIs changed.** They name the scene now,
+  `…/ut-austin-south-mall/…`.
+
+The security fixes, the limits table and the details are in the
+[changelog](https://github.com/OpenArCloud/spatialdds-py/blob/main/lib/spatialdds/CHANGELOG.md).
+
+## Not in 0.7.0
+
+Stated so nobody waits for them:
+
+- no async API;
+- no caching beyond ETag revalidation;
+- no retry policy;
+- no client-side command helper;
+- no request/reply machinery in the native layer. VPS and coverage queries are
+  a documented convention until 1.9 settles their shape;
+- no C++ or other-language port.
+
+The web client still has no DDS dependency of any kind: cyclonedds arrives
+only with `[dds]`.
 
 0.4.0 added the N.6 command surface described above; 0.5.0 made it usable
 from an embedder with a live source, which is two releases for one capability

{spatialdds-0.5.4 → spatialdds-0.7.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spatialdds"
-version = "0.5.4"
-description = "SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command."
+version = "0.7.0"
+description = "SpatialDDS for programs: a client for the web binding (Appendix N), a native DDS participant, and the reference registry behind one command."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Open AR Cloud" }]
-keywords = ["spatialdds", "spatial", "geopose", "anchors", "registry", "openarcloud"]
+keywords = ["spatialdds", "spatial", "geopose", "anchors", "registry", "dds", "cyclonedds", "openarcloud"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
@@ -32,16 +32,27 @@ dependencies = ["requests>=2.25", "websockets>=12"]
 # every publish with a 500 rather than accept something unvalidated, so
 # leaving it out of this group would ship a registry nobody can publish into.
 server = ["aiohttp>=3.8", "mcap>=1.1", "jsonschema>=4.0"]
+# Being a native DDS participant: `sd.participant(...)` beside `sd.connect(...)`.
+# cyclonedds is the binding the generated types and every endpoint use; 11.0.1
+# is the only version any of the four repositories the native layer replaces
+# had tested. mcap is the recording tap's format, and jsonschema validates
+# every written sample against the published schema before it reaches the bus.
+# Without this extra `import spatialdds` is unchanged, and `sd.participant`
+# raises `sd.MissingExtra` naming it.
+dds = ["cyclonedds>=11.0.1,<12", "mcap>=1.1", "jsonschema>=4.0"]
 
 [project.scripts]
 spatialdds-serve = "spatialdds.serve:main"
 
 [project.urls]
-Homepage = "https://github.com/OpenArCloud/spatialdds-web"
+Homepage = "https://github.com/OpenArCloud/spatialdds-py"
 Specification = "https://github.com/OpenArCloud/SpatialDDS-spec"
 
-[tool.setuptools]
-packages = ["spatialdds", "spatialdds.server"]
+# Found rather than listed: the native layer's generated bindings are a tree
+# of subpackages (`spatialdds.dds.types.spatial.core`, ...), and a hand list
+# is how one of them would go missing from a wheel.
+[tool.setuptools.packages.find]
+include = ["spatialdds", "spatialdds.*"]
 
 [tool.setuptools.package-data]
 # Everything vendored travels with the package, because the point of 0.2.0 is
@@ -49,19 +60,30 @@ packages = ["spatialdds", "spatialdds.server"]
 #
 # * `artifacts/serializer_tables.json` -- what the lift reads, in both
 #   directions. A client has no recording to learn the types from.
+# * `artifacts/registry.json` -- §3.3.2's types, §3.3.3's QoS profiles and the
+#   well-known topics, generated from the spec text at the pin by
+#   `tools/gen_registry.py`; `gates/native_registry.py` guards the drift.
 # * `artifacts/schemas/*.json` -- the 112 generated JSON Schemas. The endpoint
 #   publishes them and validates against them, and §8.4's third-party reader
 #   has nothing else to go on.
-# * `artifacts/idl/*.idl` -- the pinned IDL. A registry that starts empty
-#   boots its types from this; the tables cannot stand in because they carry
-#   no `@key`, so a keyed resource would have no instance names.
+# * `artifacts/idl/**.idl` -- the pinned IDL, the whole v1.8 tree. A registry
+#   that starts empty boots its types from this (the tables cannot stand in:
+#   they carry no `@key`), and the native layer's bindings are generated from
+#   it and its codec models it.
 # * `demo/**` -- the fountain set `--demo` serves. Byte-identical to the
 #   repository's `samples/` copy, which `tools/pack_demo.py` maintains and
 #   `gates/serve_demo.py` checks.
+# * `artifacts/openapi.{yaml,html}` -- the REST surface's OpenAPI document and
+#   its static reference page, generated by `tools/gen_openapi.py` and served
+#   at /.well-known/spatialdds/openapi; `gates/openapi.py` guards the drift.
 spatialdds = [
   "artifacts/serializer_tables.json",
+  "artifacts/registry.json",
+  "artifacts/openapi.yaml",
+  "artifacts/openapi.html",
   "artifacts/schemas/*.json",
   "artifacts/idl/*.idl",
+  "artifacts/idl/provisional/*.idl",
   "demo/*.mcap",
   "demo/manifests/*.json",
   "demo/assets/*",