@systemfsoftware/trace-taxonomy 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @systemfsoftware/trace-taxonomy
+
+## 0.0.0
+
+### Minor Changes
+
+- New package: a contracted span is declared once and started only through that declaration.
+
+  `Span.declare({ id, name, attrs })` takes an Effect Schema for the attribute record and returns a Pipeable declaration. `Span.start(span, attributes)` is a dual combinator — `effect.pipe(Span.start(span, attributes))` or `Span.start(effect, span, attributes)` — that wraps the effect in exactly the declared name with exactly those attributes. Omitting or mistyping a declared attribute is a compile error, and the declared name keeps its literal type.
+
+  `Taxonomy.make(id)` starts an immutable staged builder; `add`, `child`, `descendant`, and `forbid` are dual combinators that declare the spans they cite, deduped by id. A forbidden span's `unless` escape is an `Option`. Membership carries no emit authority: a span still starts through its declaration.
+
+  Depends on `effect` alone.

package/LICENSE

@@ -0,0 +1,203 @@
+Copyright (c) 2026 Ryan Lee (systemfsoftware)
+
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ryan Lee (systemfsoftware)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,73 @@
+# @systemfsoftware/trace-taxonomy
+
+Declare the spans a behaviour must produce, once, and start them only through that declaration.
+
+A span name that lives at its emit site is a string nobody owns: renaming it breaks every spec that mentioned it, and adding a required attribute breaks nothing at all until production. A declared span puts the name and the attribute set in one place and makes the compiler answer for both.
+
+## Install
+
+```sh
+pnpm add @systemfsoftware/trace-taxonomy effect
+```
+
+## Declare a span
+
+```ts
+import { Span } from '@systemfsoftware/trace-taxonomy'
+import { Effect, Schema } from 'effect'
+
+export const PlaceOrder = Span.declare({
+  id: 'checkout.place_order',
+  name: 'checkout.place_order',
+  attrs: Schema.Struct({
+    'app.user.id': Schema.String,
+    'app.order.items.count': Schema.Finite,
+  }),
+})
+```
+
+`Span.start` is a standalone dual combinator. Data-last it wraps the effect the span covers:
+
+```ts
+const placeOrder = (userId: string, items: number) =>
+  settleOrder(userId).pipe(
+    Span.start(PlaceOrder, { 'app.user.id': userId, 'app.order.items.count': items }),
+  )
+```
+
+Data-first it takes the effect directly: `Span.start(settleOrder(userId), PlaceOrder, attributes)`. Either way the span carries the declared name and exactly the declared attributes. Omitting `app.order.items.count`, misspelling it, or passing a string for it is a compile error. Adding a required attribute to the declaration turns every start call site red — which is the point. The declared name keeps its literal type, so a shell that must emit a span under this name reads `PlaceOrder.name` instead of restating the string.
+
+## Compose a taxonomy
+
+```ts
+import { Taxonomy } from '@systemfsoftware/trace-taxonomy'
+
+export const checkout = Taxonomy.make('checkout').pipe(
+  Taxonomy.add(PaymentRefund),
+  Taxonomy.child(PlaceOrder, PaymentCapture),
+  Taxonomy.forbid(PaymentRefund, { unless: 'error-path' }),
+)
+```
+
+`Taxonomy.make(id)` requires the taxonomy's identity before any combinator runs; every combinator is a dual, immutable step that returns a new taxonomy and declares the spans it cites (`child` and `descendant` declare both endpoints, `forbid` declares its span, and declarations dedupe by id). A taxonomy says which spans exist, which parent-child facts are legal, and which spans are forbidden on a path. Membership grants no emit authority: a span still starts through its own declaration, and a taxonomy is only ever read by whatever relates a finished trace to it.
+
+## What this package does not do
+
+It never observes, exports, collects, or samples a span; it depends on `effect` and nothing else. Reading a finished trace back and relating it to a taxonomy is [`@systemfsoftware/trace-spec`](../trace-spec), so code that only emits spans never pulls an observability SDK.
+
+## API
+
+| Export                                                       | What it is                                                  |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| `Span.declare({ id, name, attrs })`                          | The declaration; the name stays a literal type              |
+| `Span.start(span, attributes)`                               | Dual wrapper that starts the declared span around an effect |
+| `Span.Span<Attrs>`                                           | The Pipeable declaration value                              |
+| `Span.AttrsOf<T>`                                            | The attribute record a declaration promises                 |
+| `Span.AttributeValue` / `Span.AttributeRecord`               | The closed attribute value set                              |
+| `Span.isSpan`                                                | Type guard for a declaration                                |
+| `Taxonomy.make(id)`                                          | The identity-first staged builder                           |
+| `Taxonomy.add(span)`                                         | Declare a span (deduped by id)                              |
+| `Taxonomy.child` / `Taxonomy.descendant`                     | Legal parent-child facts; declare both endpoints            |
+| `Taxonomy.forbid(span, { unless })`                          | Forbid a span on a path; declares it too                    |
+| `Taxonomy.Taxonomy` / `Taxonomy.Edge` / `Taxonomy.Forbidden` | The contract types                                          |
+| `Taxonomy.isTaxonomy`                                        | Type guard for a taxonomy                                   |

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import * as Effect from "effect/Effect";
+import { Pipeable } from "effect/Pipeable";
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+declare namespace Span_d_exports {
+  export { AttributeRecord, AttributeValue, AttrsOf, Span, declare, isSpan, start };
+}
+declare const TypeId$1: unique symbol;
+type AttributeValue = string | number | boolean | ReadonlyArray<string | number | boolean>;
+type AttributeRecord = {
+  readonly [key: string]: AttributeValue;
+};
+/**
+ * A span declaration is a value, not a factory: membership grants no emit authority, and the only
+ * way to start the span is {@link start}.
+ */
+interface Span<Attrs extends AttributeRecord = AttributeRecord> extends Pipeable {
+  readonly [TypeId$1]: typeof TypeId$1;
+  readonly id: string;
+  readonly name: string;
+  readonly attrs: Schema.Schema<Attrs>;
+}
+type AttrsOf<S> = S extends Span<infer Attrs> ? Attrs : never;
+declare const isSpan: (input: unknown) => input is Span;
+declare const declare: <Attrs extends AttributeRecord, const Name extends string>(options: {
+  readonly id: string;
+  readonly name: Name;
+  readonly attrs: Schema.Schema<Attrs>;
+}) => Span<Attrs> & {
+  readonly name: Name;
+};
+declare const start: {
+  <Attrs extends AttributeRecord>(span: Span<Attrs>, attributes: Attrs): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+  <A, E, R, Attrs extends AttributeRecord>(self: Effect.Effect<A, E, R>, span: Span<Attrs>, attributes: Attrs): Effect.Effect<A, E, R>;
+};
+declare namespace Taxonomy_d_exports {
+  export { Edge, Forbidden, Taxonomy, add, child, descendant, forbid, isTaxonomy, make };
+}
+declare const TypeId: unique symbol;
+interface Edge {
+  readonly relation: 'child' | 'descendant';
+  readonly parent: Span;
+  readonly child: Span;
+}
+interface Forbidden {
+  readonly span: Span;
+  readonly unless: Option.Option<string>;
+}
+/**
+ * A taxonomy is an immutable declaration set: which spans exist, which parent-child facts are
+ * legal, and which spans a path may not carry. It is read-only evidence for relating a finished
+ * trace to a contract; it never emits a span.
+ */
+interface Taxonomy extends Pipeable {
+  readonly [TypeId]: typeof TypeId;
+  readonly id: string;
+  readonly spans: ReadonlyArray<Span>;
+  readonly edges: ReadonlyArray<Edge>;
+  readonly forbidden: ReadonlyArray<Forbidden>;
+}
+declare const isTaxonomy: (input: unknown) => input is Taxonomy;
+declare const make: (id: string) => Taxonomy;
+declare const add: {
+  (span: Span): (self: Taxonomy) => Taxonomy;
+  (self: Taxonomy, span: Span): Taxonomy;
+};
+declare const child: {
+  (parent: Span, child: Span): (self: Taxonomy) => Taxonomy;
+  (self: Taxonomy, parent: Span, child: Span): Taxonomy;
+};
+declare const descendant: {
+  (parent: Span, child: Span): (self: Taxonomy) => Taxonomy;
+  (self: Taxonomy, parent: Span, child: Span): Taxonomy;
+};
+declare const forbid: {
+  (span: Span, options?: {
+    readonly unless?: string;
+  }): (self: Taxonomy) => Taxonomy;
+  (self: Taxonomy, span: Span, options?: {
+    readonly unless?: string;
+  }): Taxonomy;
+};
+//#endregion
+export { Span_d_exports as Span, Taxonomy_d_exports as Taxonomy };

package/dist/index.mjs

@@ -0,0 +1,74 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import { Prototype } from "effect/Pipeable";
+import * as Predicate from "effect/Predicate";
+import "effect/Schema";
+import * as Arr from "effect/Array";
+import * as Option from "effect/Option";
+//#region src/Span.ts
+var Span_exports = /* @__PURE__ */ __exportAll({
+	declare: () => declare,
+	isSpan: () => isSpan,
+	start: () => start
+});
+const TypeId$1 = Symbol.for("@systemfsoftware/trace-taxonomy/Span");
+const isSpan = (input) => Predicate.hasProperty(input, TypeId$1);
+const declare = (options) => ({
+	[TypeId$1]: TypeId$1,
+	id: options.id,
+	name: options.name,
+	attrs: options.attrs,
+	...Prototype
+});
+const started = (self, span, attributes) => Effect.withSpan(self, span.name, { attributes });
+const start = dual(3, started);
+//#endregion
+//#region src/Taxonomy.ts
+var Taxonomy_exports = /* @__PURE__ */ __exportAll({
+	add: () => add,
+	child: () => child,
+	descendant: () => descendant,
+	forbid: () => forbid,
+	isTaxonomy: () => isTaxonomy,
+	make: () => make
+});
+const TypeId = Symbol.for("@systemfsoftware/trace-taxonomy/Taxonomy");
+const isTaxonomy = (input) => Predicate.hasProperty(input, TypeId);
+const make = (id) => ({
+	[TypeId]: TypeId,
+	id,
+	spans: [],
+	edges: [],
+	forbidden: [],
+	...Prototype
+});
+const declaredSpan = (spans, span) => Option.match(Arr.findFirst(spans, (declared) => declared.id === span.id), {
+	onNone: () => Arr.append(spans, span),
+	onSome: () => spans
+});
+const declared = (self, span) => ({
+	...self,
+	spans: declaredSpan(self.spans, span)
+});
+const add = dual(2, declared);
+const edgeWith = (relation, self, parent, child) => ({
+	...declared(declared(self, parent), child),
+	edges: Arr.append(self.edges, {
+		relation,
+		parent,
+		child
+	})
+});
+const child = dual(3, (self, parent, child) => edgeWith("child", self, parent, child));
+const descendant = dual(3, (self, parent, child) => edgeWith("descendant", self, parent, child));
+const forbiddenOf = (span, options) => ({
+	span,
+	unless: Option.fromUndefinedOr(options?.unless)
+});
+const forbid = dual((args) => isTaxonomy(args[0]), (self, span, options) => ({
+	...declared(self, span),
+	forbidden: Arr.append(self.forbidden, forbiddenOf(span, options))
+}));
+//#endregion
+export { Span_exports as Span, Taxonomy_exports as Taxonomy };

package/dist/rolldown-runtime-D7D4PA-g.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@systemfsoftware/trace-taxonomy",
+  "version": "0.0.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/systemfsoftware/systemfsoftware.git",
+    "directory": "packages/trace-taxonomy"
+  },
+  "description": "Declared spans for trace contracts — a contracted span is declared once with its typed required attributes and started only through that declaration.",
+  "keywords": [
+    "effect",
+    "effect-ts",
+    "opentelemetry",
+    "tracing",
+    "spans",
+    "contract",
+    "taxonomy"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-rc.116",
+    "@systemfsoftware/arethetypeswrong-cli": "^4.2.0",
+    "@types/node": "^26",
+    "effect": "4.0.0-rc.116",
+    "fast-check": "^4",
+    "oxlint": "~1.82.0",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.23.0",
+    "tstyche": "^7.2.5",
+    "typescript": "^7",
+    "vitest": "^5",
+    "@systemfsoftware/effect-gherkin-spec": "^4.2.3",
+    "@systemfsoftware/oxlint-config-recommended": "^1.1.1",
+    "@systemfsoftware/tsdown-config": "^0.1.0",
+    "@systemfsoftware/vitest-config": "^0.1.0",
+    "@systemfsoftware/tsconfig": "^1.3.6"
+  },
+  "publishConfig": {
+    "provenance": true
+  },
+  "author": "Ryan Lee <drdgvhbh@gmail.com>",
+  "homepage": "https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/trace-taxonomy#readme",
+  "bugs": "https://github.com/systemfsoftware/systemfsoftware/issues",
+  "peerDependencies": {
+    "effect": "4.0.0-rc.116"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsdown -l warn",
+    "typecheck": "tsc --noEmit --incremental",
+    "test": "vitest run",
+    "test:types": "TSTYCHE_TYPESCRIPT_MODULE=tstyche-typescript tstyche",
+    "lint": "f=${OXLINT_FORMAT:-${AGENT:+agent}}; oxlint . --format=${f:-default}",
+    "attw": "attw --pack ."
+  }
+}