@ancplua/qyl-api-schema 0.4.0 → 0.5.0

package/README.md

@@ -1,96 +1,82 @@
-# `@ancplua/qyl-api-schema`
+# @ancplua/qyl-api-schema
 
-`qyl-api-schema` is the TypeSpec source of truth for qyl's public observability API.
-
-It is not an OpenTelemetry package and it is not a server implementation. OpenTelemetry is one
-compatibility layer for qyl ingestion and instrumentation; qyl's API contracts are product contracts
-owned by qyl.
+The TypeSpec source of truth for Qyl's client-visible product API. This repository
+emits the public schema and contract artifacts; it does not implement the server,
+storage engine, or OTLP receiver.
 
 ## Contract pipeline
 
 ```text
-open-telemetry/semantic-conventions @ v1.43.0  +  semantic-conventions-genai (dev registry)
+Qyl.OpenTelemetry.SemanticConventions
         |
-        | Weaver (Qyl.OpenTelemetry.SemanticConventions repo:
-        |   generate.sh -> resolved-registry.json -> emit_typespec_keys.py)
+        | generated semantic key projection
         v
 generated/otel-keys.gen.tsp
         |
-        | TypeSpec import / lockstep key projection
-        v
-@ancplua/qyl-api-schema
-        |
-        | TypeSpec emit
         v
-OpenAPI JSON + JSON Schema + Qyl.Api.Contracts + TS contract types
+authored Qyl TypeSpec
         |
-        v
-qyl services, dashboard, tools, and generated clients
+        +----> OpenAPI and JSON Schema
+        +----> Qyl.Api.Contracts
+        +----> generated TypeScript contracts
 ```
 
-The generic OpenTelemetry key projection is the checked-in
-`generated/otel-keys.gen.tsp` under
-`ANcpLua.OpenTelemetry.SemanticConventions.Keys.*`, regenerated by the
-`Qyl.OpenTelemetry.SemanticConventions` repo's Weaver pipeline.
-This repo defines qyl domain models, routes, and response contracts under
-`Qyl.Api.Contracts.*`.
+The semantic-key projection is generated from the sibling conventions repository's
+pinned core and GenAI registries. It supplies typed names for telemetry attributes;
+Qyl domain models, routes, responses, stream events, and errors are authored here.
 
-## Published artifacts
+## Boundary
 
-| Ecosystem | Package | Purpose |
-| --- | --- | --- |
-| TypeSpec/npm | `@ancplua/qyl-api-schema` | Source schema for qyl API consumers and generators |
-| NuGet | `Qyl.Api.Contracts` | BCL-only generated C# DTOs for qyl services and consumers |
+- Every client-visible Qyl request, response, stream event, and error is defined in
+  this repository.
+- OTLP ingestion uses official OpenTelemetry protobuf messages in the runtime and is
+  not redefined here.
+- Models under `otel/` used by Qyl routes are client-facing JSON projections, not
+  OTLP wire messages.
+- Collector storage rows, ingest batches, query models, and internal projections do
+  not cross an HTTP, gRPC, MCP, streaming, or generated-client boundary.
 
-Client packages are intentionally not committed here. Generate clients from the OpenAPI document
-when needed, or add a dedicated `Qyl.Api.Client` package later. Do not generate a second C# model
-world through a client emitter.
+If a runtime shape needs to become client-visible, add it to TypeSpec first,
+regenerate the artifacts, and map the runtime model to the generated contract.
 
-## Repository layout
+## Published artifacts
 
-| Path | Role |
-| --- | --- |
-| `main.tsp` | Local compile entry point. Includes build-only emit routing. |
-| `index.tsp` | Published TypeSpec entry point. Excludes local emitter wiring. |
-| `api/` | REST and streaming API operations. |
-| `common/`, `models/`, `otel/`, `intelligence/` | qyl contract models. |
-| `emitters/` | Local TypeSpec emitters for C#, TS types, and qyl schema linting. |
-| `generated/` | Generated artifacts from `npm run compile`; never edit by hand. |
-| `packaging/Qyl.Api.Contracts.csproj` | Packs `generated/contracts` as the `Qyl.Api.Contracts` NuGet. |
+| Ecosystem | Artifact | Purpose |
+| --- | --- | --- |
+| npm/TypeSpec | `@ancplua/qyl-api-schema` | Authored schema for TypeSpec consumers |
+| NuGet | `Qyl.Api.Contracts` | BCL-only generated .NET contracts |
+| Generated | OpenAPI, JSON Schema, TypeScript | Client and validation inputs |
+
+`main.tsp` is the local compile entry point and includes emitter routing. `index.tsp`
+is the published TypeSpec entry point and contains only the client-facing contract.
 
-## Local development
+## Develop
 
 ```bash
 npm ci
 npm run lint
 npm run lint:public
 npm run compile
-./build.sh PackContractsNuget
+./build.sh Check
 ```
 
-`npm run compile` emits:
+Important generated outputs include:
 
 - `generated/openapi/qyl.openapi.json`
-- `generated/json-schema/qyl-api-schema.json`
+- `generated/json-schema/qyl-api-schema`
 - `generated/contracts/**/*.cs`
 - `generated/ts-types/**`
 
-## Hard boundaries
-
-- Do not add TypeSpec C# server scaffold emitters.
-- Do not add DuckDB/storage schema emitters. Physical storage schema lives in qyl runtime mapping specs.
-- Do not commit generated ASP.NET projects, controllers, mocks, or starter
-  docs that tell maintainers to fill in mock business logic.
-- Do not add compatibility shims for old package IDs or namespaces.
-- Do not hand-edit generated output. Fix TypeSpec, emitter code, or generator inputs, then regenerate.
-- Do not reintroduce legacy qyl API package IDs or namespaces.
-
-## Publishing
-
-Publishing is fully automated via GitHub Actions OIDC **trusted publishing** — no stored secrets, no
-API keys. Publish a GitHub Release whose tag is `vMAJOR.MINOR.PATCH[-prerelease]`; `publish.yml` then,
-all-or-nothing, packs and validates the artifacts, stamps that single tag-derived version onto both,
-pushes `Qyl.Api.Contracts` to nuget.org (NuGet/login OIDC) and publishes `@ancplua/qyl-api-schema` to
-npmjs.org (npm trusted publishing + provenance). NuGet pushes first (idempotent) and npm last
-(immutable), so a partial failure re-runs cleanly. See [VERSIONING.md](VERSIONING.md) for how the
-version is derived from the tag. There are no long-lived publish tokens to manage or rotate.
+Generated files are not editing surfaces. Change TypeSpec or the owning emitter and
+regenerate.
+
+## Publish
+
+GitHub Actions publishes both registries through OIDC trusted publishing. A release
+tag supplies one version for npm and NuGet. The workflow validates and packs first,
+publishes in an ordered restartable sequence, waits for indexed artifacts, and then
+smokes clean consumers. No long-lived npm or NuGet token is stored.
+
+## License
+
+Apache-2.0