Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions .github/workflows/enterprise-adapter.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Enterprise adapter tests — verifies the Upsilon lineage adapter preserves
# portable sigrank/0.1-draft semantics and passes the standalone fixture pack
# from sigrank-standard on every push/PR touching the adapter or its tests.
name: Enterprise Adapter

on:
push:
branches: [main]
paths:
- "enterprise-adapter/**"
- "tests/enterprise-adapter*.test.mjs"
- ".github/workflows/enterprise-adapter.yml"
pull_request:
paths:
- "enterprise-adapter/**"
- "tests/enterprise-adapter*.test.mjs"
- ".github/workflows/enterprise-adapter.yml"

jobs:
adapter:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Checkout sigrank-standard (authoritative fixture pack)
uses: actions/checkout@v4
with:
repository: SunrisesIllNeverSee/sigrank-standard
path: _sigrank-standard
# Checkout main, then pin to the exact SHA. actions/checkout cannot
# resolve a bare commit SHA as a ref, so we checkout main with
# full history and reset to the pinned commit.
ref: main
fetch-depth: 0

- name: Pin sigrank-standard to pinned ref
working-directory: _sigrank-standard
run: git reset --hard ${{ vars.SIGRANK_STANDARD_REF || 'c73f152' }}

- uses: actions/setup-node@v4
with:
node-version: "22"

- name: Enterprise adapter unit tests
run: node --test tests/enterprise-adapter.test.mjs

- name: Standalone Standard conformance gate
env:
SIGRANK_STANDARD_REF: ${{ vars.SIGRANK_STANDARD_REF || 'c73f152' }}
SIGRANK_STANDARD_PATH: ${{ github.workspace }}/_sigrank-standard
run: node --test tests/enterprise-adapter-conformance.test.mjs
73 changes: 73 additions & 0 deletions enterprise-adapter/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Upsilon Enterprise Lineage Adapter

**Version:** `upsilon/enterprise-adapter/0.1-draft`
**Accepts:** `sigrank/0.1-draft` portable observations
**Governance:** MO§ES™
**Product:** Upsilon
**Proof surface:** SigRank (for eligible observations only)

## Purpose

The enterprise lineage adapter bridges the portable SigRank Standard
(`sigrank/0.1-draft`) into Upsilon's governed enterprise observation
namespace. It preserves the portable core (I/O/W/R + five metrics) while
adding enterprise derivations in a **separate namespace** that never
leaks into the portable record.

## Namespace separation

```text
sigrank/0.1-draft portable record
spec, timestamp, source, telemetry, metrics, warnings
↓ (adapter accepts this as input)
upsilon/enterprise-adapter/0.1-draft enterprise observation
portable: (preserved verbatim — spec, telemetry, metrics, warnings)
enterprise: (separate namespace — cohort, window, lineage, derivations)
```

The portable record is never mutated. Enterprise fields are added in a
separate `enterprise` object. A consumer that only reads the portable
fields gets exactly the `sigrank/0.1-draft` record.

## What the adapter preserves

- source I/O/W/R telemetry (non-negative integers, null for unavailable)
- observed zero versus unavailable/null (distinct semantics)
- timestamp and observation window
- provider/model/tool source
- collector version
- Standard version (`sigrank/0.1-draft`)
- provenance and warnings

## What the adapter adds (enterprise namespace only)

- `cohort_id` — tenant-scoped cohort identifier
- `window` — observation window (start, end)
- `lineage` — chain of observations linking to outcomes
- `derivations` — MO§ES-governed enterprise metrics (construction, composite
scores, outcome correlations) — **never** in the portable namespace
- `collector_version` — adapter version that produced this observation
- `privacy_mode` — anonymous, pseudonymous, private, or identified

## Excluded from portable compatibility

Construction, Build Archetypes, RS05, Scale V, rank, percentile, quality
scores, cycle times, bug counts, and outcome data remain enterprise-only.
They cannot enter the portable metric namespace.

## Validation

The adapter validates pilot manifests against the canonical pilot schema
(`docs/pilot-manifest.schema.json`). Fixtures cover:

- complete telemetry (all four pillars)
- partial cache (cache_write or cache_read unavailable)
- zero values (zero cache_read distinct from unavailable)
- invalid version (rejects records not declaring `sigrank/0.1-draft`)

## Interpretation boundary

Upsilon describes observable token-processing patterns. Enterprise
derivations are MO§ES-governed and labeled DEVELOPMENTAL. Neither the
portable metrics nor the enterprise derivations prove cognition, work
quality, employee productivity, or business outcomes.
180 changes: 180 additions & 0 deletions enterprise-adapter/adapter.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
/**
* enterprise-adapter/adapter.mjs
*
* Upsilon Enterprise Lineage Adapter — versioned adapter that accepts
* sigrank/0.1-draft portable observations and produces enterprise
* observations in a separate namespace.
*
* The portable record is preserved verbatim. Enterprise derivations are
* added in a separate `enterprise` object that never leaks into the
* portable metric namespace.
*
* Adapter version: upsilon/enterprise-adapter/0.1-draft
* Standard version: sigrank/0.1-draft
* Governance: MO§ES™
* Product: Upsilon
*/

export const ADAPTER_VERSION = "upsilon/enterprise-adapter/0.1-draft";
export const STANDARD_VERSION = "sigrank/0.1-draft";

/**
* Build an enterprise observation from a portable sigrank/0.1-draft record.
*
* @param {object} portableRecord - A sigrank/0.1-draft record (spec, timestamp,
* source, telemetry, metrics, warnings).
* @param {object} enterpriseContext - Enterprise context (cohort_id, window,
* lineage, derivations, privacy_mode, collector_version).
* @returns {object} Enterprise observation with portable + enterprise namespaces.
* @throws {Error} If the portable record does not declare sigrank/0.1-draft.
*/
export function buildEnterpriseObservation(portableRecord, enterpriseContext = {}) {
// Validate the portable record declares the correct Standard version
if (!portableRecord || portableRecord.spec !== STANDARD_VERSION) {
throw new Error(
`Enterprise adapter requires a ${STANDARD_VERSION} portable record; got spec="${portableRecord?.spec ?? "undefined"}"`,
);
}

// Validate required portable fields are present
const requiredPortable = ["spec", "timestamp", "source", "telemetry", "metrics"];
for (const field of requiredPortable) {
if (!(field in portableRecord)) {
throw new Error(`Portable record missing required field: ${field}`);
}
}

// Validate telemetry primitives are non-negative integers or null
const t = portableRecord.telemetry;
if (!Number.isInteger(t.input) || t.input < 0) {
throw new Error("Portable telemetry.input must be a non-negative integer");
}
if (!Number.isInteger(t.output) || t.output < 0) {
throw new Error("Portable telemetry.output must be a non-negative integer");
}
if (t.cache_write !== null && (!Number.isInteger(t.cache_write) || t.cache_write < 0)) {
throw new Error("Portable telemetry.cache_write must be a non-negative integer or null");
}
if (t.cache_read !== null && (!Number.isInteger(t.cache_read) || t.cache_read < 0)) {
throw new Error("Portable telemetry.cache_read must be a non-negative integer or null");
}

// Validate the five portable metrics are present (values may be null)
const requiredMetrics = ["yield", "leverage", "velocity", "snr", "dev10x"];
for (const m of requiredMetrics) {
if (!(m in portableRecord.metrics)) {
throw new Error(`Portable metrics missing required metric: ${m}`);
}
}

// Validate no enterprise fields leaked into the portable record
const forbiddenPortableMetrics = [
"construction", "scale_v", "rs05", "build_archetype",
"rank", "percentile", "quality_score", "cycle_time", "bug_count",
"outcome", "lineage",
];
for (const forbidden of forbiddenPortableMetrics) {
if (forbidden in portableRecord.metrics) {
throw new Error(`Enterprise metric "${forbidden}" leaked into portable metrics`);
}
}
const forbiddenPortableFields = [
"outcome", "lineage", "quality_score", "cycle_time", "bug_count", "enterprise_data",
];
for (const forbidden of forbiddenPortableFields) {
if (forbidden in portableRecord) {
throw new Error(`Enterprise field "${forbidden}" leaked into portable record`);
}
}

// Build the enterprise observation — portable is preserved verbatim,
// enterprise is a separate namespace
return {
adapter_version: ADAPTER_VERSION,
standard_version: STANDARD_VERSION,
portable: {
spec: portableRecord.spec,
timestamp: portableRecord.timestamp,
source: { ...portableRecord.source },
telemetry: { ...portableRecord.telemetry },
metrics: { ...portableRecord.metrics },
warnings: [...(portableRecord.warnings || [])],
},
enterprise: {
collector_version: enterpriseContext.collector_version || ADAPTER_VERSION,
cohort_id: enterpriseContext.cohort_id ?? null,
window: enterpriseContext.window
? { start: enterpriseContext.window.start ?? null, end: enterpriseContext.window.end ?? null }
: { start: null, end: null },
lineage: enterpriseContext.lineage
? {
chain_id: enterpriseContext.lineage.chain_id ?? null,
parent_observation_id: enterpriseContext.lineage.parent_observation_id ?? null,
micro_eval: enterpriseContext.lineage.micro_eval ?? null,
}
: { chain_id: null, parent_observation_id: null, micro_eval: null },
derivations: enterpriseContext.derivations
? { ...enterpriseContext.derivations }
: {},
privacy_mode: enterpriseContext.privacy_mode || "anonymous",
governance_label: enterpriseContext.governance_label || "DEVELOPMENTAL",
},
};
}

/**
* Validate a pilot manifest against the canonical pilot schema.
* Returns a list of errors (empty = valid).
*/
export function validatePilotManifest(manifest, schema) {
const errors = [];

function checkNode(value, node, path) {
if (node.const !== undefined && value !== node.const) {
errors.push(`${path}: expected const ${JSON.stringify(node.const)}, got ${JSON.stringify(value)}`);
return;
}
if (node.enum !== undefined && !node.enum.includes(value)) {
errors.push(`${path}: expected one of ${JSON.stringify(node.enum)}, got ${JSON.stringify(value)}`);
}
if (node.type !== undefined) {
const types = Array.isArray(node.type) ? node.type : [node.type];
const matched = types.some((ty) => {
if (value === null) return ty === "null";
if (ty === "integer") return Number.isInteger(value);
if (ty === "number") return typeof value === "number" && !Number.isNaN(value);
if (ty === "string") return typeof value === "string";
if (ty === "boolean") return typeof value === "boolean";
if (ty === "object") return typeof value === "object" && value !== null && !Array.isArray(value);
if (ty === "array") return Array.isArray(value);
return false;
});
if (!matched) errors.push(`${path}: expected type ${JSON.stringify(node.type)}, got ${typeof value}`);
}
if (node.minimum !== undefined && typeof value === "number" && value < node.minimum) {
errors.push(`${path}: value ${value} below minimum ${node.minimum}`);
}
if (node.minLength !== undefined && typeof value === "string" && value.length < node.minLength) {
errors.push(`${path}: string length ${value.length} below minLength ${node.minLength}`);
}
if (node.required !== undefined && typeof value === "object" && value !== null && !Array.isArray(value)) {
for (const req of node.required) {
if (!(req in value)) errors.push(`${path}: missing required field "${req}"`);
}
}
if (node.additionalProperties === false && typeof value === "object" && value !== null && !Array.isArray(value)) {
const allowed = Object.keys(node.properties || {});
for (const key of Object.keys(value)) {
if (!allowed.includes(key)) errors.push(`${path}: additional property "${key}" not allowed`);
}
}
if (node.properties !== undefined && typeof value === "object" && value !== null && !Array.isArray(value)) {
for (const [key, subSchema] of Object.entries(node.properties)) {
if (key in value) checkNode(value[key], subSchema, `${path}.${key}`);
}
}
}

checkNode(manifest, schema, "manifest");
return errors;
}
28 changes: 28 additions & 0 deletions enterprise-adapter/fixtures/complete-telemetry.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"id": "complete-telemetry",
"description": "Complete telemetry — all four pillars present, all five metrics computed, no warnings.",
"portable": {
"spec": "sigrank/0.1-draft",
"timestamp": "2026-08-27T00:00:00.000Z",
"source": { "provider": "anthropic", "model": "claude-sonnet-4", "tool": "claude-code" },
"telemetry": { "input": 1251211, "output": 11296121, "cache_write": 128196310, "cache_read": 2555179769 },
"metrics": { "yield": 18436.98, "leverage": 2042.2, "velocity": 9.028, "snr": 0.9003, "dev10x": 3.31 },
"warnings": []
},
"enterprise_context": {
"cohort_id": "acme_50",
"window": { "start": "2026-07-01", "end": "2026-07-30" },
"lineage": { "chain_id": "chain_001", "parent_observation_id": null, "micro_eval": "MAINTAIN" },
"derivations": { "construction": 0.0502, "composite_score": 78.5, "outcome_correlation": 0.42 },
"privacy_mode": "pseudonymous",
"governance_label": "DEVELOPMENTAL"
},
"expected": {
"adapter_version": "upsilon/enterprise-adapter/0.1-draft",
"standard_version": "sigrank/0.1-draft",
"portable_preserved": true,
"enterprise_has_construction": true,
"portable_has_no_construction": true,
"portable_has_no_enterprise_fields": true
}
}
17 changes: 17 additions & 0 deletions enterprise-adapter/fixtures/invalid-version.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"id": "invalid-version",
"description": "Invalid version — the portable record declares a spec other than sigrank/0.1-draft. The adapter must reject this with an error, not silently accept it.",
"portable": {
"spec": "sigrank/0.2-draft",
"timestamp": "2026-08-27T00:00:00.000Z",
"source": { "provider": "anthropic", "model": "claude-sonnet-4", "tool": "claude-code" },
"telemetry": { "input": 1000, "output": 5000, "cache_write": 500, "cache_read": 3000 },
"metrics": { "yield": 15, "leverage": 3, "velocity": 5, "snr": 0.8333, "dev10x": 0.48 },
"warnings": []
},
"enterprise_context": {},
"expected": {
"should_throw": true,
"error_matches": "sigrank/0.1-draft"
}
}
31 changes: 31 additions & 0 deletions enterprise-adapter/fixtures/partial-cache.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
{
"id": "partial-cache",
"description": "Partial cache — cache_write and cache_read unavailable (null). Yield, Leverage, and 10xDEV are null. Velocity and SNR are computed. The adapter must preserve null semantics and not coerce null to zero.",
"portable": {
"spec": "sigrank/0.1-draft",
"timestamp": "2026-08-27T00:00:00.000Z",
"source": { "provider": "openai", "model": "gpt-4o", "tool": "copilot" },
"telemetry": { "input": 5000, "output": 12000, "cache_write": null, "cache_read": null },
"metrics": { "yield": null, "leverage": null, "velocity": 2.4, "snr": 0.7059, "dev10x": null },
"warnings": [
"cache_write is unavailable; 10xDEV is undefined.",
"cache_read is unavailable; Yield, Leverage, and 10xDEV are undefined."
]
},
"enterprise_context": {
"cohort_id": "acme_50",
"privacy_mode": "pseudonymous",
"derivations": { "construction": null, "composite_score": null }
},
"expected": {
"adapter_version": "upsilon/enterprise-adapter/0.1-draft",
"standard_version": "sigrank/0.1-draft",
"portable_preserved": true,
"portable_cache_write_is_null": true,
"portable_cache_read_is_null": true,
"portable_yield_is_null": true,
"portable_leverage_is_null": true,
"portable_dev10x_is_null": true,
"portable_velocity_is_number": true
}
}
Loading
Loading