@dryvcode/author 0.0.1

package/README.md

@@ -0,0 +1,341 @@
+# @dryvcode/author
+
+Strongly typed TypeScript authoring for Dryv. This package defines software meaning. It does not serialize Runtime IR, select template packs, generate application source code, or write project files.
+
+Every Dryv Author implementation must compile into the same canonical `dryv.ir/v1alpha1` Runtime IR.
+
+## Model
+
+```text
+full definitions -> Group registration -> lightweight typed refs
+                                      \
+                                       -> App composition
+```
+
+Groups own full declarations. Registration names supply local identity and return lightweight typed refs. Relationships use those refs rather than raw builders.
+
+```ts
+import { dryv, field, property, schema } from "@dryvcode/author";
+
+const shared = dryv.group({ name: "shared" });
+const values = shared.properties({
+  UserId: property.string.uuid(),
+  Email: property.string.email(),
+  CreatedAt: property.temporal.instant().precision("millisecond"),
+});
+
+const users = dryv.group({ name: "users" });
+const schemas = users.schemas({
+  User: schema({
+    id: field(values.UserId).system(),
+    email: field(values.Email),
+    createdAt: field(values.CreatedAt).system(),
+  }),
+});
+
+schemas.User.field("email");
+
+export default dryv.app({ name: "example" }).groups(shared, users);
+```
+
+The compiler qualifies local identities at the Author/Runtime boundary:
+
+```text
+users + User -> users.User -> #/schemas/users.User
+```
+
+Runtime registries remain flat by semantic kind. Group ancestry affects semantic scope, never canonical declaration identity. `.` is reserved for compiler qualification and cannot appear in authored Group names, App names, or registration keys.
+
+## Registered refs
+
+Reusable declarations must be registered before another declaration can reference them.
+
+```ts
+const Id = property.string.uuid();
+
+// invalid: raw definition
+// field(Id)
+
+const shared = dryv.group({ name: "shared" });
+const values = shared.properties({ Id });
+
+field(values.Id); // valid
+```
+
+This rule applies across Schemas, Properties, Policies, Operations, Events, Failures, Workflows, Views, Presentations, Features, and Applications. `unknown()` and `dynamic()` are intrinsic targets and remain inline.
+
+## Properties
+
+`group.properties({...})` classifies reusable value meaning into the canonical registries:
+
+```text
+primitives
+enums
+composites
+literals
+unions
+records
+tuples
+generics
+temporal
+```
+
+There are no reusable `unknown` or `dynamic` registries.
+
+Examples:
+
+```ts
+const base = shared.properties({
+  Id: property.string.uuid(),
+  Name: property.string(),
+  Count: property.number.nonNegativeInteger(),
+  Active: property.literal("active"),
+  CreatedAt: property.temporal.instant().precision("millisecond"),
+});
+
+const advanced = shared.properties({
+  Coordinates: property.composite({
+    x: field(base.Count),
+    y: field(base.Count),
+  }),
+  Identifier: property.union({
+    discriminant: "kind",
+    members: { id: base.Id, active: base.Active },
+  }),
+  Pair: property.tuple(base.Id, base.Active),
+  Labels: property.record(base.Id, base.Name),
+  Box: property.generic.define((T) =>
+    property.composite({ value: field(T) }),
+  ),
+});
+```
+
+Generic applications consume a registered generic definition and registered arguments:
+
+```ts
+shared.properties({
+  UserBox: property.generic.apply(advanced.Box, [schemas.User]),
+});
+```
+
+Properties may carry their property-specific description/examples/lifecycle semantics. Universal `tags` and structured `explanations` are only exposed where the Runtime contract supports them; they are not silently accepted on Properties or Expressions.
+
+## Expressions
+
+Expressions are named reusable declarations with a closed Dryv vocabulary.
+
+```ts
+import { context, expression, value } from "@dryvcode/author";
+
+const expressions = users.expressions({
+  IsOwner: expression.equal(
+    context("actor", "id"),
+    context("resource", "ownerId"),
+  ),
+  CurrentDate: expression.date(
+    expression.inTimeZone(expression.now(), "Africa/Nairobi"),
+  ),
+  DefaultName: value("unknown"),
+});
+```
+
+Registered Expression refs are consumed by Policy rules, temporal dynamic bounds, Schema defaults, and composite invariants. There is no arbitrary custom-AST escape hatch.
+
+## Policies
+
+Policies are reusable semantic requirements, not framework guards or middleware definitions.
+
+```ts
+const policies = users.policies({
+  CanRead: policy()
+    .requires({ actor: schemas.User, resource: schemas.User })
+    .provides({ id: values.UserId })
+    .rule(expressions.IsOwner),
+});
+```
+
+A Policy may intentionally have no rule. Context values are registered Property/Schema refs and rules are registered boolean Expression refs.
+
+Groups and Applications may also declare scope policies:
+
+```ts
+users.policies(policies.CanRead);
+
+dryv.app({ name: "example" }).groups(users).policies(policies.CanRead);
+```
+
+Effective inherited scope is Runtime/inspection responsibility; Authoring records only the declared scope.
+
+## Schemas
+
+Schema field meaning is flat in Author state and canonical Runtime IR. There is no field `usage` wrapper.
+
+```ts
+const users = dryv.group({ name: "users" });
+const schemas = users.schemas({
+  User: schema({
+    id: field(values.UserId).system(),
+    email: field(values.Email)
+      .optional()
+      .nullable()
+      .query({ filter: ["equal", "contains"], sort: true, search: true }),
+    names: field(values.Name).array({ min: 1 }),
+  }),
+});
+```
+
+Field helpers include:
+
+- `.required()` / `.optional()`;
+- `.nullable()`;
+- `.array(...)`;
+- `.default(...)`;
+- `.system()` / `.createOnly()`;
+- `.query(...)`;
+- `.sensitive()`;
+- `.policy(...)`;
+- `.relation(...)` / `.related(...)`;
+- `.sources(...)`;
+- `.tags(...)` / `.explain(...)` where Runtime field metadata is supported.
+
+The retired `.mutation(...)` shortcut is intentionally not supported.
+
+### Effective field references and relations
+
+`SchemaRef.field(...)` represents semantic effective-field identity. The compiler emits `{ $ref: <schema>, field: <name> }`, not a physical `/fields/...` pointer.
+
+```ts
+const entities = users.schemas({
+  Entity: schema({ id: field(values.UserId) }).abstract(),
+});
+
+users.schemas({
+  Membership: schema({
+    ownerId: field(values.UserId).relation({
+      target: () => entities.Entity.field("id"),
+      cardinality: relation.manyToOne(),
+      onDelete: relation.restrict(),
+    }),
+  }),
+});
+```
+
+### Field-local sources
+
+There is no root Source declaration or `group.sources(...)` registry. Source meaning belongs to the Schema field that consumes it.
+
+```ts
+const operations = users.operations({
+  ListStatuses: operation().outputs({
+    statuses: list(ref(values.Name)),
+  }),
+});
+
+users.schemas({
+  Filter: schema({
+    status: field(values.Name).sources({
+      choices: source.options(operations.ListStatuses).output("statuses"),
+    }),
+  }),
+});
+```
+
+Input bindings use `source.value()` for the consuming field value or `source.field(() => schemaRef.field(...))` for another effective Schema field. If a source operation has exactly one output, the compiler may infer it; otherwise `.output(...)` is required.
+
+### Storage facets
+
+There is no root Storage declaration or storage registry. Portable storage semantics belong to `schema.facets.storage`.
+
+```ts
+const stored = users.schemas({
+  User: schema({
+    id: field(values.UserId),
+    email: field(values.Email),
+  }).facets({
+    storage: storage("users")
+      .primaryKey("id")
+      .indexes({ fields: ["email"], unique: true }),
+  }),
+});
+```
+
+Concrete stored Schemas require a storage name. Abstract Schemas may contribute inherited storage rules without a concrete name.
+
+### Projection selectors
+
+Projection selection is Author-only convenience. The compiler resolves selectors against effective source fields and emits explicit canonical `projection.fields`.
+
+```ts
+users.schemas({
+  UserRead: schema({}).projection(
+    projection(stored.User)
+      .purpose("read")
+      .pick("id", "email")
+      .rename({ email: "contactEmail" })
+      .usage({ email: { optional: true } }),
+  ),
+});
+```
+
+Supported helpers are `.pick(...)`, `.omit(...)`, `.rename(...)`, `.usage(...)`, `.purpose(...)`, and `.policies(...)`. Projection-from-projection, projection inheritance, abstract projections, projection storage facets, unknown selections, and output collisions are rejected.
+
+## Universal semantic metadata
+
+The hardened Runtime contracts currently expose universal metadata on:
+
+- Application;
+- Group;
+- Policy;
+- Schema;
+- Schema/composite fields.
+
+Authoring uses:
+
+```ts
+const users = dryv
+  .group({ name: "users" })
+  .tags("domain")
+  .explain("info", "User capabilities");
+```
+
+Tags are normalized deterministically. Explanations compile as `{ kind, text }`. Empty/default metadata is omitted.
+
+## App composition
+
+The root App is the canonical root Application composition.
+
+```ts
+export default dryv
+  .app({ name: "example", description: "Example" })
+  .groups(shared, users)
+  .policies(policies.CanRead)
+  .facets({ http: { root: "/api" } });
+```
+
+The App may compose Groups, policies, HTTP scope, features, surfaces, and presentations. It is not a separate semantic model.
+
+## Compiler boundary
+
+Author state remains implementation-specific. The TypeScript compiler owns qualification, reference resolution, authoring-convenience expansion, canonical spelling, and rejection of ambiguous/unrepresentable constructs.
+
+Important boundary rules:
+
+```text
+Group scope + local name -> <group>.<item>
+projection selectors     -> explicit projection.fields
+field source helpers     -> field-local canonical sources
+storage helper           -> schema.facets.storage
+TypeScript camelCase     -> canonical Dryv spelling where required
+```
+
+The Author package itself never serializes Runtime IR.
+
+## Development
+
+```bash
+bun install
+bun run format
+bun run check
+```
+
+`bun run check` verifies formatting, strict TypeScript types, tests, build output, and the public-package smoke import.

package/dist/behavior/duration.d.ts

@@ -0,0 +1,7 @@
+import type { DurationState } from "../contracts/index.js";
+export type DurationInput = DurationState | number;
+export declare function seconds(value: number): DurationState;
+export declare function minutes(value: number): DurationState;
+export declare function hours(value: number): DurationState;
+export declare function resolveDuration(value: DurationInput, field: string): DurationState;
+//# sourceMappingURL=duration.d.ts.map

package/dist/behavior/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../src/behavior/duration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,MAAM,CAAC;AAYnD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAEpD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAEpD;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAElD;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,GACZ,aAAa,CAEf"}

package/dist/behavior/duration.js

@@ -0,0 +1,20 @@
+function duration(value, field) {
+    const secondsValue = typeof value === "number" ? value : value.seconds;
+    if (!Number.isInteger(secondsValue) || secondsValue <= 0) {
+        throw new TypeError(`${field} must be a positive integer number of seconds`);
+    }
+    return { seconds: secondsValue };
+}
+export function seconds(value) {
+    return duration(value, "seconds");
+}
+export function minutes(value) {
+    return duration(value * 60, "minutes");
+}
+export function hours(value) {
+    return duration(value * 3600, "hours");
+}
+export function resolveDuration(value, field) {
+    return duration(value, field);
+}
+//# sourceMappingURL=duration.js.map

package/dist/behavior/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../src/behavior/duration.ts"],"names":[],"mappings":"AAIA,SAAS,QAAQ,CAAC,KAAoB,EAAE,KAAa;IACnD,MAAM,YAAY,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IACvE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,+CAA+C,CACxD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,QAAQ,CAAC,KAAK,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,KAAa;IACjC,OAAO,QAAQ,CAAC,KAAK,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,KAAoB,EACpB,KAAa;IAEb,OAAO,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/dist/behavior/event.d.ts

@@ -0,0 +1,23 @@
+import type { ExplanationKindState, EventRoleState } from "../contracts/index.js";
+import type { EventState } from "../contracts/index.js";
+import { Declaration } from "../foundation/declaration.js";
+import type { InferValueRef, OperationRef, ValueRef, WorkflowRef } from "../foundation/ref.js";
+export declare class EventDeclaration<TPayload = never> extends Declaration<"event"> {
+    readonly __payload?: TPayload;
+    private _description?;
+    private _tags;
+    private _explanations;
+    private _role?;
+    private _payload?;
+    private _listeners;
+    constructor();
+    description(value: string): this;
+    tags(...values: readonly string[]): this;
+    explain(kind: ExplanationKindState, text: string): this;
+    role(value: EventRoleState): this;
+    payload<V extends ValueRef>(value: V): EventDeclaration<InferValueRef<V>>;
+    listeners(...values: readonly (OperationRef | WorkflowRef)[]): this;
+    toState(): EventState;
+}
+export declare function event(): EventDeclaration;
+//# sourceMappingURL=event.d.ts.map

package/dist/behavior/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/behavior/event.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,oBAAoB,EAEpB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAQ1B,qBAAa,gBAAgB,CAAC,QAAQ,GAAG,KAAK,CAAE,SAAQ,WAAW,CAAC,OAAO,CAAC;IAC1E,SAAiB,SAAS,CAAC,EAAE,QAAQ,CAAC;IACtC,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,KAAK,CAAC,CAAiB;IAC/B,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,UAAU,CAAsC;IAExD,cAEC;IAED,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAG/B;IAED,IAAI,CAAC,GAAG,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAGvC;IAED,OAAO,CAAC,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAGtD;IAED,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAGhC;IAED,OAAO,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,gBAAgB,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAGxE;IAED,SAAS,CAAC,GAAG,MAAM,EAAE,SAAS,CAAC,YAAY,GAAG,WAAW,CAAC,EAAE,GAAG,IAAI,CAGlE;IAEQ,OAAO,IAAI,UAAU,CAgB7B;CACF;AAED,wBAAgB,KAAK,IAAI,gBAAgB,CAExC"}

package/dist/behavior/event.js

@@ -0,0 +1,57 @@
+import { explanation, normalizeTags, optionalSemanticMetadata, } from "../foundation/metadata.js";
+import { Declaration } from "../foundation/declaration.js";
+import { optionalDescription, optionalOwner, optionalOrigin, requireText, } from "../foundation/metadata.js";
+export class EventDeclaration extends Declaration {
+    _description;
+    _tags = [];
+    _explanations = [];
+    _role;
+    _payload;
+    _listeners = [];
+    constructor() {
+        super("event");
+    }
+    description(value) {
+        this._description = requireText(value, "event description");
+        return this;
+    }
+    tags(...values) {
+        this._tags = [...normalizeTags(values, "tags")];
+        return this;
+    }
+    explain(kind, text) {
+        this._explanations.push(explanation(kind, text, "explanation"));
+        return this;
+    }
+    role(value) {
+        this._role = value;
+        return this;
+    }
+    payload(value) {
+        this._payload = value;
+        return this;
+    }
+    listeners(...values) {
+        this._listeners = [...values];
+        return this;
+    }
+    toState() {
+        return {
+            identity: this.identity,
+            kind: "event",
+            ...optionalSemanticMetadata(this._tags, this._explanations),
+            ...(this._role === undefined ? {} : { role: this._role }),
+            ...(this._payload === undefined ? {} : { payload: this._payload.ref() }),
+            listeners: this._listeners.map((value) => value.kind === "operation"
+                ? { kind: "operation", operation: value.ref() }
+                : { kind: "workflow", workflow: value.ref() }),
+            ...optionalDescription(this._description),
+            ...optionalOwner(this._group, this._feature),
+            ...optionalOrigin(this._origin),
+        };
+    }
+}
+export function event() {
+    return new EventDeclaration();
+}
+//# sourceMappingURL=event.js.map

package/dist/behavior/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../src/behavior/event.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,aAAa,EACb,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAOvD,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAE/B,MAAM,OAAO,gBAAmC,SAAQ,WAAoB;IAElE,YAAY,CAAU;IACtB,KAAK,GAAa,EAAE,CAAC;IACrB,aAAa,GAAuB,EAAE,CAAC;IACvC,KAAK,CAAkB;IACvB,QAAQ,CAAY;IACpB,UAAU,GAAmC,EAAE,CAAC;IAExD;QACE,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;IAED,WAAW,CAAC,KAAa;QACvB,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,GAAG,MAAyB;QAC/B,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,IAA0B,EAAE,IAAY;QAC9C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,KAAqB;QACxB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAqB,KAAQ;QAClC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,OAAO,IAAqD,CAAC;IAC/D,CAAC;IAED,SAAS,CAAC,GAAG,MAA+C;QAC1D,IAAI,CAAC,UAAU,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAEQ,OAAO;QACd,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,IAAI,EAAE,OAAO;YACb,GAAG,wBAAwB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC;YAC3D,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YACzD,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC;YACxE,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACvC,KAAK,CAAC,IAAI,KAAK,WAAW;gBACxB,CAAC,CAAC,EAAE,IAAI,EAAE,WAAoB,EAAE,SAAS,EAAE,KAAK,CAAC,GAAG,EAAE,EAAE;gBACxD,CAAC,CAAC,EAAE,IAAI,EAAE,UAAmB,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,EAAE,EAAE,CACzD;YACD,GAAG,mBAAmB,CAAC,IAAI,CAAC,YAAY,CAAC;YACzC,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC;YAC5C,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;SAChC,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,KAAK;IACnB,OAAO,IAAI,gBAAgB,EAAE,CAAC;AAChC,CAAC"}

package/dist/behavior/failure.d.ts

@@ -0,0 +1,19 @@
+import type { ExplanationKindState } from "../contracts/index.js";
+import type { FailureState } from "../contracts/index.js";
+import type { TypeSpec } from "../definitions/types/spec.js";
+import { Declaration } from "../foundation/declaration.js";
+export declare class FailureDeclaration extends Declaration<"failure"> {
+    #private;
+    private _description?;
+    private _tags;
+    private _explanations;
+    private _payload?;
+    constructor(code: string);
+    description(value: string): this;
+    tags(...values: readonly string[]): this;
+    explain(kind: ExplanationKindState, text: string): this;
+    payload<T>(value: TypeSpec<T>): this;
+    toState(): FailureState;
+}
+export declare function failure(code: string): FailureDeclaration;
+//# sourceMappingURL=failure.d.ts.map

package/dist/behavior/failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../src/behavior/failure.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAoB,MAAM,mBAAmB,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAQvD,qBAAa,kBAAmB,SAAQ,WAAW,CAAC,SAAS,CAAC;;IAE5D,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,CAAoB;IAErC,YAAY,IAAI,EAAE,MAAM,EAGvB;IAED,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAG/B;IAED,IAAI,CAAC,GAAG,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAGvC;IAED,OAAO,CAAC,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAGtD;IAED,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAGnC;IAEQ,OAAO,IAAI,YAAY,CAa/B;CACF;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAExD"}

package/dist/behavior/failure.js

@@ -0,0 +1,48 @@
+import { explanation, normalizeTags, optionalSemanticMetadata, } from "../foundation/metadata.js";
+import { Declaration } from "../foundation/declaration.js";
+import { optionalDescription, optionalOwner, optionalOrigin, requireText, } from "../foundation/metadata.js";
+export class FailureDeclaration extends Declaration {
+    #code;
+    _description;
+    _tags = [];
+    _explanations = [];
+    _payload;
+    constructor(code) {
+        super("failure");
+        this.#code = requireText(code, "failure code");
+    }
+    description(value) {
+        this._description = requireText(value, "failure description");
+        return this;
+    }
+    tags(...values) {
+        this._tags = [...normalizeTags(values, "tags")];
+        return this;
+    }
+    explain(kind, text) {
+        this._explanations.push(explanation(kind, text, "explanation"));
+        return this;
+    }
+    payload(value) {
+        this._payload = value;
+        return this;
+    }
+    toState() {
+        return {
+            identity: this.identity,
+            kind: "failure",
+            ...optionalSemanticMetadata(this._tags, this._explanations),
+            code: this.#code,
+            ...(this._payload === undefined
+                ? {}
+                : { payload: this._payload.toTypeState() }),
+            ...optionalDescription(this._description),
+            ...optionalOwner(this._group, this._feature),
+            ...optionalOrigin(this._origin),
+        };
+    }
+}
+export function failure(code) {
+    return new FailureDeclaration(code);
+}
+//# sourceMappingURL=failure.js.map

package/dist/behavior/failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.js","sourceRoot":"","sources":["../../src/behavior/failure.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,aAAa,EACb,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAE/B,MAAM,OAAO,kBAAmB,SAAQ,WAAsB;IACnD,KAAK,CAAS;IACf,YAAY,CAAU;IACtB,KAAK,GAAa,EAAE,CAAC;IACrB,aAAa,GAAuB,EAAE,CAAC;IACvC,QAAQ,CAAqB;IAErC,YAAY,IAAY;QACtB,KAAK,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IACjD,CAAC;IAED,WAAW,CAAC,KAAa;QACvB,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,GAAG,MAAyB;QAC/B,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,IAA0B,EAAE,IAAY;QAC9C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAI,KAAkB;QAC3B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAEQ,OAAO;QACd,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,IAAI,EAAE,SAAS;YACf,GAAG,wBAAwB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC;YAC3D,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS;gBAC7B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;YAC7C,GAAG,mBAAmB,CAAC,IAAI,CAAC,YAAY,CAAC;YACzC,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC;YAC5C,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;SAChC,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/dist/behavior/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./duration.js";
+export * from "./policy.js";
+export * from "./failure.js";
+export * from "./event.js";
+export * from "./operation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/behavior/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/behavior/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}

package/dist/behavior/index.js

@@ -0,0 +1,6 @@
+export * from "./duration.js";
+export * from "./policy.js";
+export * from "./failure.js";
+export * from "./event.js";
+export * from "./operation.js";
+//# sourceMappingURL=index.js.map

package/dist/behavior/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/behavior/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}

package/dist/behavior/operation.d.ts

@@ -0,0 +1,72 @@
+import type { ExecutionMode, ExplanationKindState, OperationRoleState, OperationState } from "../contracts/index.js";
+import { Declaration } from "../foundation/declaration.js";
+import type { EventRef, FailureRef, OperationPortRef, OperationRef, PolicyRef, TupleIndex, ValueRefTuple } from "../foundation/ref.js";
+import { type DurationInput } from "./duration.js";
+import type { FacetDeclaration } from "../interfaces/facet.js";
+export interface OperationFacetsInput {
+    readonly http?: FacetDeclaration;
+    readonly websocket?: FacetDeclaration;
+    readonly schedule?: FacetDeclaration;
+}
+export declare class OperationDeclaration<TInputs extends ValueRefTuple = readonly [], TOutputs extends ValueRefTuple = readonly []> extends Declaration<"operation"> {
+    readonly __inputs?: TInputs;
+    readonly __outputs?: TOutputs;
+    private _description?;
+    private _role?;
+    private _tags;
+    private _explanations;
+    private _inputs;
+    private _outputs;
+    private _failures;
+    private _emits;
+    private _authenticated;
+    private _policies;
+    private _mode;
+    private _timeout?;
+    private _rateLimit?;
+    private _cache?;
+    private _transaction?;
+    private _retry?;
+    private _idempotency?;
+    private _audit?;
+    private _invalidates;
+    private _facets;
+    constructor();
+    description(value: string): this;
+    role(value: OperationRoleState): this;
+    tags(...values: readonly string[]): this;
+    explain(kind: ExplanationKindState, text: string): this;
+    inputs<const T extends ValueRefTuple>(...values: T): OperationDeclaration<T, TOutputs>;
+    outputs<const T extends ValueRefTuple>(...values: T): OperationDeclaration<TInputs, T>;
+    input<I extends TupleIndex<TInputs>>(index: I): OperationPortRef<import("../foundation/ref.js").InferValueRef<TInputs[I]>, "input">;
+    output<I extends TupleIndex<TOutputs>>(index: I): OperationPortRef<import("../foundation/ref.js").InferValueRef<TOutputs[I]>, "output">;
+    failures(...values: readonly FailureRef[]): this;
+    emits(...values: readonly EventRef[]): this;
+    authenticated(value?: boolean): this;
+    requires(...values: readonly PolicyRef[]): this;
+    mode(value: ExecutionMode): this;
+    async(value?: boolean): this;
+    timeout(value: DurationInput): this;
+    rateLimit(options: {
+        readonly limit: number;
+        readonly window: DurationInput;
+    }): this;
+    cache(options: {
+        readonly ttl: DurationInput;
+    }): this;
+    transactional(required?: boolean): this;
+    retry(options: {
+        readonly maxAttempts: number;
+        readonly backoff?: DurationInput;
+    }): this;
+    idempotentBy<I extends TupleIndex<TInputs>>(input: I): this;
+    audit(required?: boolean): this;
+    invalidates(...values: readonly OperationRef[]): this;
+    /** Operation reachability, at most one facet per kind (decision 0012). */
+    facets(values: OperationFacetsInput): this;
+    toState(): OperationState;
+}
+export declare function operation(): OperationDeclaration;
+export type OperationInputs<T> = T extends OperationDeclaration<infer I, infer _O> ? I : T extends OperationRef<infer I, infer _O> ? I : never;
+export type OperationOutputs<T> = T extends OperationDeclaration<infer _I, infer O> ? O : T extends OperationRef<infer _I, infer O> ? O : never;
+//# sourceMappingURL=operation.d.ts.map

package/dist/behavior/operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../src/behavior/operation.ts"],"names":[],"mappings":"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"}