@ankhorage/capability 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ankhorage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+<!-- markdownlint-disable MD013 MD033 -->
+<!-- This file is generated by Paradox. Do not edit manually. -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @ankhorage/capability
+
+![license: MIT](././paradox/badges/license.svg) ![npm: v0.2.2](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![paradox: canonical](././paradox/badges/docs.svg)
+
+Generic runtime validation, normalization, equality, and catalog operations for Ankhorage capabilities.
+
+## Generated documentation
+
+- [Interactive documentation app](././paradox/index.html)
+- [Public API reference](././paradox/exports.md)
+- [Component registry](././paradox/components.md)
+- [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
+- [Module relationships](././paradox/diagrams/module-relationships.mmd)
+- [Export graph](././paradox/diagrams/export-graph.mmd)
+- [areCapabilitiesEqual sequence](././paradox/diagrams/sequences/are-capabilities-equal.mmd)
+- [areCapabilityCatalogsEqual sequence](././paradox/diagrams/sequences/are-capability-catalogs-equal.mmd)
+- [isCapabilityCatalog sequence](././paradox/diagrams/sequences/is-capability-catalog.mmd)
+- [isCapabilityId sequence](././paradox/diagrams/sequences/is-capability-id.mmd)
+- [normalizeCapability sequence](././paradox/diagrams/sequences/normalize-capability.mmd)

package/dist/features/capability/areCapabilitiesEqual.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Compare capability descriptors independently of record keys and unordered collection ordering. */
+export declare function areCapabilitiesEqual(left: Capability, right: Capability): boolean;

package/dist/features/capability/areCapabilitiesEqual.js

@@ -0,0 +1,6 @@
+import { isDeepEqual } from '@ankhorage/utility/object';
+import { normalizeCapability } from './normalizeCapability.js';
+/*** Compare capability descriptors independently of record keys and unordered collection ordering. */
+export function areCapabilitiesEqual(left, right) {
+    return isDeepEqual(normalizeCapability(left), normalizeCapability(right));
+}

package/dist/features/capability/isCapability.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Validate an untrusted value as one complete portable capability descriptor. */
+export declare function isCapability(value: unknown): value is Capability;

package/dist/features/capability/isCapability.js

@@ -0,0 +1,5 @@
+import { parseCapability } from './parseCapability.js';
+/*** Validate an untrusted value as one complete portable capability descriptor. */
+export function isCapability(value) {
+    return parseCapability(value) !== null;
+}

package/dist/features/capability/isCapabilityId.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Validate a stable dot-separated identifier for one capability. */
+export declare function isCapabilityId(value: unknown): value is Capability['id'];

package/dist/features/capability/isCapabilityId.js

@@ -0,0 +1,7 @@
+import { isNonEmptyString } from '@ankhorage/utility/string';
+/*** Validate a stable dot-separated identifier for one capability. */
+export function isCapabilityId(value) {
+    return (isNonEmptyString(value) &&
+        value.split('.').length >= 2 &&
+        value.split('.').every(isNonEmptyString));
+}

package/dist/features/capability/normalizeCapability.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Return a capability with unordered access and binding-role collections sorted and deduplicated. */
+export declare function normalizeCapability(capability: Capability): Capability;

package/dist/features/capability/normalizeCapability.js

@@ -0,0 +1,27 @@
+import { uniqueSortedStrings } from '@ankhorage/utility/array';
+const CAPABILITY_ACCESS = ['emit', 'invoke', 'read', 'subscribe', 'write'];
+const CAPABILITY_BINDING_ROLES = ['source', 'target'];
+/*** Return a capability with unordered access and binding-role collections sorted and deduplicated. */
+export function normalizeCapability(capability) {
+    return {
+        id: capability.id,
+        owner: capability.owner,
+        access: uniqueSortedStrings(capability.access).filter(isCapabilityAccess),
+        binding: {
+            kind: capability.binding.kind,
+            bindableAs: uniqueSortedStrings(capability.binding.bindableAs).filter(isCapabilityBindingRole),
+        },
+        ...(capability.label === undefined ? {} : { label: capability.label }),
+        ...(capability.description === undefined ? {} : { description: capability.description }),
+        ...(capability.input === undefined ? {} : { input: capability.input }),
+        ...(capability.output === undefined ? {} : { output: capability.output }),
+    };
+}
+/*** Retain one known portable capability access operation after generic string normalization. */
+function isCapabilityAccess(value) {
+    return CAPABILITY_ACCESS.includes(value);
+}
+/*** Retain one known portable capability binding direction after generic string normalization. */
+function isCapabilityBindingRole(value) {
+    return CAPABILITY_BINDING_ROLES.includes(value);
+}

package/dist/features/capability/parseCapability.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Parse one complete portable capability descriptor from an untrusted value. */
+export declare function parseCapability(value: unknown): Capability | null;

package/dist/features/capability/parseCapability.js

@@ -0,0 +1,152 @@
+import { isRecord, readOwnProperty } from '@ankhorage/utility/object';
+import { isNonEmptyString, isOptionalString } from '@ankhorage/utility/string';
+import { isCapabilityId } from './isCapabilityId.js';
+const CAPABILITY_ACCESS = ['emit', 'invoke', 'read', 'subscribe', 'write'];
+const CAPABILITY_BINDING_KINDS = [
+    'action',
+    'api',
+    'auth',
+    'authorization',
+    'context',
+    'event',
+    'permission',
+    'state',
+    'storage',
+];
+const CAPABILITY_BINDING_ROLES = ['source', 'target'];
+/*** Parse one complete portable capability descriptor from an untrusted value. */
+export function parseCapability(value) {
+    if (!isRecord(value))
+        return null;
+    if (!isCapabilityId(value.id) || !isNonEmptyString(value.owner))
+        return null;
+    if (!isCapabilityAccessList(value.access) || !isCapabilityBinding(value.binding))
+        return null;
+    if (!isOptionalString(value.label) || !isOptionalString(value.description))
+        return null;
+    if (!isOptionalDataSchemaSlot(value.input) || !isOptionalDataSchemaSlot(value.output))
+        return null;
+    return {
+        id: value.id,
+        owner: value.owner,
+        access: value.access,
+        binding: value.binding,
+        ...(value.label === undefined ? {} : { label: value.label }),
+        ...(value.description === undefined ? {} : { description: value.description }),
+        ...(value.input === undefined ? {} : { input: value.input }),
+        ...(value.output === undefined ? {} : { output: value.output }),
+    };
+}
+/*** Validate a non-empty list of supported capability access operations. */
+function isCapabilityAccessList(value) {
+    return Array.isArray(value) && value.length > 0 && value.every(isCapabilityAccess);
+}
+/*** Validate one supported capability access operation. */
+function isCapabilityAccess(value) {
+    return typeof value === 'string' && CAPABILITY_ACCESS.includes(value);
+}
+/*** Validate the portable binding shape attached to a capability descriptor. */
+function isCapabilityBinding(value) {
+    return (isRecord(value) &&
+        isCapabilityBindingKind(value.kind) &&
+        Array.isArray(value.bindableAs) &&
+        value.bindableAs.every(isCapabilityBindingRole));
+}
+/*** Validate one supported portable capability binding family. */
+function isCapabilityBindingKind(value) {
+    return typeof value === 'string' && CAPABILITY_BINDING_KINDS.includes(value);
+}
+/*** Validate one supported capability binding direction. */
+function isCapabilityBindingRole(value) {
+    return typeof value === 'string' && CAPABILITY_BINDING_ROLES.includes(value);
+}
+/*** Validate an omitted or structurally valid portable data-schema slot. */
+function isOptionalDataSchemaSlot(value) {
+    return value === undefined || isDataSchemaSlot(value);
+}
+/*** Validate one portable data-schema slot without importing an executable Contracts helper. */
+function isDataSchemaSlot(value) {
+    return (isRecord(value) &&
+        (value.schema === undefined || isDataSchema(value.schema)) &&
+        (value.schemaRef === undefined || isDataSchemaRef(value.schemaRef)));
+}
+/*** Validate the serializable recursive data-schema shape used by capability slots. */
+function isDataSchema(value) {
+    return (isRecord(value) &&
+        isDataSchemaMetadata(value) &&
+        isDataSchemaStructure(value) &&
+        isDataSchemaValues(value));
+}
+/*** Validate descriptive and object-shape metadata for one data schema. */
+function isDataSchemaMetadata(value) {
+    return (isOptionalDataSchemaType(value.type) &&
+        isOptionalString(value.title) &&
+        isOptionalString(value.description) &&
+        isOptionalString(value.format) &&
+        (value.nullable === undefined || typeof value.nullable === 'boolean') &&
+        isOptionalStringArray(value.required) &&
+        isOptionalDataSchemaProperties(value.properties) &&
+        isOptionalAdditionalProperties(value.additionalProperties));
+}
+/*** Validate recursive composition and reference fields for one data schema. */
+function isDataSchemaStructure(value) {
+    return ((value.items === undefined || isDataSchema(value.items)) &&
+        isOptionalDataSchemaComposition(value) &&
+        (value.ref === undefined || isDataSchemaRef(value.ref)));
+}
+/*** Validate serializable constant, default, and enum fields for one data schema. */
+function isDataSchemaValues(value) {
+    return (isOptionalSerializableValue(value.const) &&
+        isOptionalSerializableValue(value.default) &&
+        isOptionalSerializableValueArray(value.enum));
+}
+/*** Validate an omitted data-schema type or supported primitive type declaration. */
+function isOptionalDataSchemaType(value) {
+    const dataSchemaTypes = ['array', 'boolean', 'integer', 'null', 'number', 'object', 'string'];
+    return (value === undefined ||
+        (typeof value === 'string' && dataSchemaTypes.includes(value)) ||
+        (Array.isArray(value) &&
+            value.every((entry) => typeof entry === 'string' && dataSchemaTypes.includes(entry))));
+}
+/*** Validate an omitted array of required property names. */
+function isOptionalStringArray(value) {
+    return (value === undefined ||
+        (Array.isArray(value) && value.every((entry) => typeof entry === 'string')));
+}
+/*** Validate an omitted map of nested data schemas. */
+function isOptionalDataSchemaProperties(value) {
+    return value === undefined || (isRecord(value) && Object.values(value).every(isDataSchema));
+}
+/*** Validate an omitted additional-properties declaration. */
+function isOptionalAdditionalProperties(value) {
+    return value === undefined || typeof value === 'boolean' || isDataSchema(value);
+}
+/*** Validate optional schema intersections and alternatives from own properties only. */
+function isOptionalDataSchemaComposition(value) {
+    return ['allOf', 'anyOf', 'oneOf'].every((key) => isOptionalDataSchemaArray(readOwnProperty(value, key)));
+}
+/*** Validate an omitted recursive data-schema collection. */
+function isOptionalDataSchemaArray(value) {
+    return value === undefined || (Array.isArray(value) && value.every(isDataSchema));
+}
+/*** Validate a schema reference with the portable string identifier contract. */
+function isDataSchemaRef(value) {
+    return isRecord(value) && typeof value.id === 'string';
+}
+/*** Validate an omitted JSON-serializable scalar, array, or record value. */
+function isOptionalSerializableValue(value) {
+    return value === undefined || isSerializableValue(value);
+}
+/*** Validate an omitted array of JSON-serializable values. */
+function isOptionalSerializableValueArray(value) {
+    return value === undefined || (Array.isArray(value) && value.every(isSerializableValue));
+}
+/*** Validate one JSON-serializable value recursively. */
+function isSerializableValue(value) {
+    return (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        (Array.isArray(value) && value.every(isSerializableValue)) ||
+        (isRecord(value) && Object.values(value).every(isSerializableValue)));
+}

package/dist/features/catalog/areCapabilityCatalogsEqual.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Compare capability catalogs independently of authored catalog and unordered descriptor collection ordering. */
+export declare function areCapabilityCatalogsEqual(left: readonly Capability[], right: readonly Capability[]): boolean;

package/dist/features/catalog/areCapabilityCatalogsEqual.js

@@ -0,0 +1,6 @@
+import { isDeepEqual } from '@ankhorage/utility/object';
+import { normalizeCapabilityCatalog } from './normalizeCapabilityCatalog.js';
+/*** Compare capability catalogs independently of authored catalog and unordered descriptor collection ordering. */
+export function areCapabilityCatalogsEqual(left, right) {
+    return isDeepEqual(normalizeCapabilityCatalog(left), normalizeCapabilityCatalog(right));
+}

package/dist/features/catalog/isCapabilityCatalog.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Validate a capability catalog with complete descriptors and unique stable identifiers. */
+export declare function isCapabilityCatalog(value: unknown): value is readonly Capability[];

package/dist/features/catalog/isCapabilityCatalog.js

@@ -0,0 +1,5 @@
+import { parseCapabilityCatalog } from './parseCapabilityCatalog.js';
+/*** Validate a capability catalog with complete descriptors and unique stable identifiers. */
+export function isCapabilityCatalog(value) {
+    return parseCapabilityCatalog(value) !== null;
+}

package/dist/features/catalog/normalizeCapabilityCatalog.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Normalize trusted catalog descriptors and sort them by stable capability identifier. */
+export declare function normalizeCapabilityCatalog(catalog: readonly Capability[]): readonly Capability[];

package/dist/features/catalog/normalizeCapabilityCatalog.js

@@ -0,0 +1,7 @@
+import { normalizeCapability } from '../capability/normalizeCapability.js';
+/*** Normalize trusted catalog descriptors and sort them by stable capability identifier. */
+export function normalizeCapabilityCatalog(catalog) {
+    return catalog
+        .map(normalizeCapability)
+        .toSorted((left, right) => left.id.localeCompare(right.id));
+}

package/dist/features/catalog/parseCapabilityCatalog.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from '@ankhorage/contracts/capability';
+/*** Parse a capability catalog and reject invalid descriptors or duplicate stable identifiers. */
+export declare function parseCapabilityCatalog(value: unknown): readonly Capability[] | null;

package/dist/features/catalog/parseCapabilityCatalog.js

@@ -0,0 +1,12 @@
+import { parseCapability } from '../capability/parseCapability.js';
+/*** Parse a capability catalog and reject invalid descriptors or duplicate stable identifiers. */
+export function parseCapabilityCatalog(value) {
+    if (!Array.isArray(value))
+        return null;
+    const capabilities = value.map(parseCapability);
+    if (capabilities.some((capability) => capability === null))
+        return null;
+    const parsedCapabilities = capabilities.filter((capability) => capability !== null);
+    const ids = new Set(parsedCapabilities.map((capability) => capability.id));
+    return ids.size === parsedCapabilities.length ? parsedCapabilities : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { areCapabilitiesEqual } from './features/capability/areCapabilitiesEqual.js';
+export { isCapability } from './features/capability/isCapability.js';
+export { isCapabilityId } from './features/capability/isCapabilityId.js';
+export { normalizeCapability } from './features/capability/normalizeCapability.js';
+export { parseCapability } from './features/capability/parseCapability.js';
+export { areCapabilityCatalogsEqual } from './features/catalog/areCapabilityCatalogsEqual.js';
+export { isCapabilityCatalog } from './features/catalog/isCapabilityCatalog.js';
+export { normalizeCapabilityCatalog } from './features/catalog/normalizeCapabilityCatalog.js';
+export { parseCapabilityCatalog } from './features/catalog/parseCapabilityCatalog.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { areCapabilitiesEqual } from './features/capability/areCapabilitiesEqual.js';
+export { isCapability } from './features/capability/isCapability.js';
+export { isCapabilityId } from './features/capability/isCapabilityId.js';
+export { normalizeCapability } from './features/capability/normalizeCapability.js';
+export { parseCapability } from './features/capability/parseCapability.js';
+export { areCapabilityCatalogsEqual } from './features/catalog/areCapabilityCatalogsEqual.js';
+export { isCapabilityCatalog } from './features/catalog/isCapabilityCatalog.js';
+export { normalizeCapabilityCatalog } from './features/catalog/normalizeCapabilityCatalog.js';
+export { parseCapabilityCatalog } from './features/catalog/parseCapabilityCatalog.js';

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@ankhorage/capability",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.2",
+  "description": "Generic runtime validation, normalization, equality, and catalog operations for Ankhorage capabilities.",
+  "license": "MIT",
+  "homepage": "https://github.com/ankhorage/capability#readme",
+  "bugs": {
+    "url": "https://github.com/ankhorage/capability/issues"
+  },
+  "keywords": [
+    "ankhorage",
+    "capability",
+    "validation",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankhorage/capability.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test",
+    "test:standalone": "bun run build && bun test tests/standalone.test.ts",
+    "docs": "bunx @ankhorage/paradox && ankhorage-prettier --write README.md paradox",
+    "lint": "ankhorage-eslint . --max-warnings=0",
+    "lint:fix": "ankhorage-eslint . --fix --max-warnings=0",
+    "format": "ankhorage-prettier --write .",
+    "format:check": "ankhorage-prettier --check .",
+    "knip:check": "ankhorage-knip",
+    "changeset": "ankhorage-changeset",
+    "changeset:status": "ankhorage-changeset status --since=origin/main",
+    "version-packages": "ankhorage-changeset version"
+  },
+  "dependencies": {
+    "@ankhorage/contracts": "^26.0.0",
+    "@ankhorage/utility": "^1.9.85"
+  },
+  "devDependencies": {
+    "@ankhorage/doctor": "^0.14.5",
+    "@ankhorage/devtools": "^2.3.6",
+    "@ankhorage/paradox": "^0.2.28",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.4",
+    "typescript": "^6.0.3"
+  },
+  "packageManager": "bun@1.4.2"
+}