@fintekkers/ledger-models 0.4.9 → 0.4.11

package/node/wrappers/models/lazy-hydrate-race.test.ts

@@ -0,0 +1,144 @@
+// Concurrent-hydrate race test for Portfolio + Transaction wrappers.
+// TypeScript has no shared-state threads, but Promise.all + a mock LinkResolver
+// covers the same shape: N parallel `await wrapper.hydrate()` calls on
+// wrappers that share a UUID. Contract:
+//
+//   1. Resolver's in-flight dedup collapses N hydrate() calls into one RPC.
+//   2. Every awaiter sees the resolved proto.
+//   3. The shared LinkCache singleton ends on the resolved entry.
+
+import LinkResolver from "../util/link-resolver";
+import * as LinkCacheModule from "../util/link-cache";
+import Portfolio from "./portfolio/portfolio";
+import Transaction from "./transaction/transaction";
+import { UUID } from "./utils/uuid";
+
+import { PortfolioProto } from "../../fintekkers/models/portfolio/portfolio_pb";
+import { TransactionProto } from "../../fintekkers/models/transaction/transaction_pb";
+import { LocalTimestampProto } from "../../fintekkers/models/util/local_timestamp_pb";
+import { Timestamp } from "google-protobuf/google/protobuf/timestamp_pb";
+import { QueryPortfolioResponseProto } from "../../fintekkers/requests/portfolio/query_portfolio_response_pb";
+import { QueryTransactionResponseProto } from "../../fintekkers/requests/transaction/query_transaction_response_pb";
+
+function makeAsOf(seconds = 1_700_000_000): LocalTimestampProto {
+  const ts = new Timestamp();
+  ts.setSeconds(seconds);
+  ts.setNanos(0);
+  const lt = new LocalTimestampProto();
+  lt.setTimestamp(ts);
+  lt.setTimeZone("UTC");
+  return lt;
+}
+
+interface CallLog {
+  count: number;
+}
+
+function mockPortfolioClient(resolved: PortfolioProto, log: CallLog) {
+  return {
+    getByIds: (
+      _req: any,
+      cb: (err: Error | null, res: QueryPortfolioResponseProto) => void,
+    ) => {
+      log.count++;
+      const r = new QueryPortfolioResponseProto();
+      r.setPortfolioResponseList([resolved]);
+      setImmediate(() => cb(null, r));
+    },
+  } as any;
+}
+
+function mockTransactionClient(resolved: TransactionProto, log: CallLog) {
+  return {
+    getByIds: (
+      _req: any,
+      cb: (err: Error | null, res: QueryTransactionResponseProto) => void,
+    ) => {
+      log.count++;
+      const r = new QueryTransactionResponseProto();
+      r.setTransactionResponseList([resolved]);
+      setImmediate(() => cb(null, r));
+    },
+  } as any;
+}
+
+// Throw-on-call client for the unused entity types.
+function throwingClient(name: string) {
+  return {
+    getByIds: () => {
+      throw new Error(`${name} client should not be invoked in this test`);
+    },
+  } as any;
+}
+
+describe("lazy hydrate — concurrent hydrate() collapses to one RPC", () => {
+  beforeEach(() => {
+    LinkCacheModule.SECURITY.clear();
+    LinkCacheModule.PORTFOLIO.clear();
+    LinkCacheModule.TRANSACTION.clear();
+    LinkResolver.setDefault(undefined);
+  });
+
+  test("Portfolio: 16 concurrent hydrate() calls → 1 RPC, all observe RESOLVED", async () => {
+    const uuid = UUID.random();
+    const asOf = makeAsOf();
+
+    const resolved = new PortfolioProto();
+    resolved.setUuid(uuid.toUUIDProto());
+    resolved.setAsOf(asOf);
+    resolved.setIsLink(false);
+    resolved.setPortfolioName("RESOLVED");
+
+    const log: CallLog = { count: 0 };
+    const resolver = new LinkResolver({
+      portfolioClient: mockPortfolioClient(resolved, log),
+      securityClient: throwingClient("security"),
+      transactionClient: throwingClient("transaction"),
+    });
+
+    // Build 16 wrappers from the same link-mode proto.
+    const linkProto = new PortfolioProto();
+    linkProto.setUuid(uuid.toUUIDProto());
+    linkProto.setAsOf(asOf);
+    linkProto.setIsLink(true);
+    const wrappers = Array.from({ length: 16 }, () => new Portfolio(linkProto));
+
+    const hydrated = await Promise.all(wrappers.map((w) => w.hydrate(resolver)));
+
+    expect(log.count).toBe(1);
+    for (const w of hydrated) {
+      expect(w.getPortfolioName()).toBe("RESOLVED");
+    }
+  });
+
+  test("Transaction: 16 concurrent hydrate() calls → 1 RPC, all observe resolved trade name", async () => {
+    const uuid = UUID.random();
+    const asOf = makeAsOf();
+
+    const resolved = new TransactionProto();
+    resolved.setUuid(uuid.toUUIDProto());
+    resolved.setAsOf(asOf);
+    resolved.setIsLink(false);
+    resolved.setTradeName("RESOLVED-TRADE");
+
+    const log: CallLog = { count: 0 };
+    const resolver = new LinkResolver({
+      transactionClient: mockTransactionClient(resolved, log),
+      securityClient: throwingClient("security"),
+      portfolioClient: throwingClient("portfolio"),
+    });
+
+    const linkProto = new TransactionProto();
+    linkProto.setUuid(uuid.toUUIDProto());
+    linkProto.setAsOf(asOf);
+    linkProto.setIsLink(true);
+    const wrappers = Array.from({ length: 16 }, () => new Transaction(linkProto));
+
+    const hydrated = await Promise.all(wrappers.map((w) => w.hydrate(resolver)));
+
+    expect(log.count).toBe(1);
+    for (const w of hydrated) {
+      expect(w.proto.getTradeName()).toBe("RESOLVED-TRADE");
+    }
+  });
+});

package/node/wrappers/models/lazy-hydrate.bench.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node/wrappers/models/lazy-hydrate.bench.test.js

@@ -0,0 +1,121 @@
+"use strict";
+// End-to-end perf bench for Transaction wrapper lazy hydration.
+// Run: `npx jest node/wrappers/models/lazy-hydrate.bench.ts` (jest runs
+// .ts files via ts-jest; stdout shows the bench output).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const LinkCacheModule = __importStar(require("../util/link-cache"));
+const transaction_1 = __importDefault(require("./transaction/transaction"));
+const uuid_1 = require("./utils/uuid");
+const portfolio_pb_1 = require("../../fintekkers/models/portfolio/portfolio_pb");
+const transaction_pb_1 = require("../../fintekkers/models/transaction/transaction_pb");
+const local_timestamp_pb_1 = require("../../fintekkers/models/util/local_timestamp_pb");
+const datetime_1 = require("./utils/datetime");
+const timestamp_pb_1 = require("google-protobuf/google/protobuf/timestamp_pb");
+const SIZES = [10, 100, 1000, 10000];
+function makeAsOf() {
+    const ts = new timestamp_pb_1.Timestamp();
+    ts.setSeconds(1700000000);
+    ts.setNanos(0);
+    const lt = new local_timestamp_pb_1.LocalTimestampProto();
+    lt.setTimestamp(ts);
+    lt.setTimeZone("UTC");
+    return lt;
+}
+function runBench(n) {
+    const asOf = makeAsOf();
+    const asOfZdt = new datetime_1.ZonedDateTime(asOf);
+    const links = [];
+    const txnUuids = [];
+    const portUuids = [];
+    for (let i = 0; i < n; i++) {
+        const txnUuid = uuid_1.UUID.random();
+        const portUuid = uuid_1.UUID.random();
+        txnUuids.push(txnUuid.toString());
+        portUuids.push(portUuid.toString());
+        const resolvedPortfolio = new portfolio_pb_1.PortfolioProto();
+        resolvedPortfolio.setUuid(portUuid.toUUIDProto());
+        resolvedPortfolio.setAsOf(asOf);
+        resolvedPortfolio.setIsLink(false);
+        resolvedPortfolio.setPortfolioName(`P-${portUuid.toString().slice(0, 8)}`);
+        const resolved = new transaction_pb_1.TransactionProto();
+        resolved.setUuid(txnUuid.toUUIDProto());
+        resolved.setAsOf(asOf);
+        resolved.setIsLink(false);
+        resolved.setTradeName(`T-${txnUuid.toString().slice(0, 8)}`);
+        resolved.setPortfolio(resolvedPortfolio);
+        LinkCacheModule.TRANSACTION.put(txnUuid.toString(), resolved, asOfZdt);
+        LinkCacheModule.PORTFOLIO.put(portUuid.toString(), resolvedPortfolio, asOfZdt);
+        const link = new transaction_pb_1.TransactionProto();
+        link.setUuid(txnUuid.toUUIDProto());
+        link.setAsOf(asOf);
+        link.setIsLink(true);
+        links.push(link);
+    }
+    if (global.gc)
+        global.gc();
+    const heapBefore = process.memoryUsage().heapUsed;
+    const t0 = process.hrtime.bigint();
+    let sink = 0;
+    for (const link of links) {
+        const t = new transaction_1.default(link);
+        // Trigger lazy hydrate via getter that calls ensureHydrated.
+        const name = t.proto.getIsLink() ? "" : t.proto.getTradeName();
+        // Workaround: TS wrappers' ensureHydrated is private and accessors
+        // on Transaction are reads through proto. Hit a typed accessor:
+        const portfolio = t.getPortfolio();
+        if (portfolio)
+            sink++;
+        if (name === "" && portfolio)
+            sink++;
+    }
+    const t1 = process.hrtime.bigint();
+    const heapAfter = process.memoryUsage().heapUsed;
+    const elapsedNs = Number(t1 - t0);
+    const elapsedMs = elapsedNs / 1e6;
+    const perOpUs = elapsedNs / n / 1000;
+    const heapDeltaKb = (heapAfter - heapBefore) / 1024;
+    // eslint-disable-next-line no-console
+    console.log(`N=${n.toString().padStart(6)}  elapsed=${elapsedMs.toFixed(2).padStart(9)} ms  ` +
+        `per_op=${perOpUs.toFixed(2).padStart(8)} us  ` +
+        `heap_delta=${heapDeltaKb.toFixed(2).padStart(8)} KiB  reads=${sink}`);
+    for (const u of txnUuids)
+        LinkCacheModule.TRANSACTION.evict(u);
+    for (const u of portUuids)
+        LinkCacheModule.PORTFOLIO.evict(u);
+}
+// Wrap in describe so jest treats it as a suite; the test body is the bench.
+describe("lazy-hydrate bench", () => {
+    test("Transaction across 10/100/1000/10000 sizes", () => {
+        // eslint-disable-next-line no-console
+        console.log("# ts bench: lazy-hydrate Transaction via pre-warmed LinkCache");
+        for (const n of SIZES)
+            runBench(n);
+    }, 60000);
+});
+//# sourceMappingURL=lazy-hydrate.bench.test.js.map

package/node/wrappers/models/lazy-hydrate.bench.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-hydrate.bench.test.js","sourceRoot":"","sources":["lazy-hydrate.bench.test.ts"],"names":[],"mappings":"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"}

package/node/wrappers/models/lazy-hydrate.bench.test.ts

@@ -0,0 +1,103 @@
+// End-to-end perf bench for Transaction wrapper lazy hydration.
+// Run: `npx jest node/wrappers/models/lazy-hydrate.bench.ts` (jest runs
+// .ts files via ts-jest; stdout shows the bench output).
+
+import * as LinkCacheModule from "../util/link-cache";
+import Transaction from "./transaction/transaction";
+import { UUID } from "./utils/uuid";
+
+import { PortfolioProto } from "../../fintekkers/models/portfolio/portfolio_pb";
+import { TransactionProto } from "../../fintekkers/models/transaction/transaction_pb";
+import { LocalTimestampProto } from "../../fintekkers/models/util/local_timestamp_pb";
+import { ZonedDateTime } from "./utils/datetime";
+import { Timestamp } from "google-protobuf/google/protobuf/timestamp_pb";
+
+const SIZES = [10, 100, 1_000, 10_000];
+
+function makeAsOf(): LocalTimestampProto {
+  const ts = new Timestamp();
+  ts.setSeconds(1_700_000_000);
+  ts.setNanos(0);
+  const lt = new LocalTimestampProto();
+  lt.setTimestamp(ts);
+  lt.setTimeZone("UTC");
+  return lt;
+}
+
+function runBench(n: number) {
+  const asOf = makeAsOf();
+  const asOfZdt = new ZonedDateTime(asOf);
+  const links: TransactionProto[] = [];
+  const txnUuids: string[] = [];
+  const portUuids: string[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const txnUuid = UUID.random();
+    const portUuid = UUID.random();
+    txnUuids.push(txnUuid.toString());
+    portUuids.push(portUuid.toString());
+
+    const resolvedPortfolio = new PortfolioProto();
+    resolvedPortfolio.setUuid(portUuid.toUUIDProto());
+    resolvedPortfolio.setAsOf(asOf);
+    resolvedPortfolio.setIsLink(false);
+    resolvedPortfolio.setPortfolioName(`P-${portUuid.toString().slice(0, 8)}`);
+
+    const resolved = new TransactionProto();
+    resolved.setUuid(txnUuid.toUUIDProto());
+    resolved.setAsOf(asOf);
+    resolved.setIsLink(false);
+    resolved.setTradeName(`T-${txnUuid.toString().slice(0, 8)}`);
+    resolved.setPortfolio(resolvedPortfolio);
+
+    LinkCacheModule.TRANSACTION.put(txnUuid.toString(), resolved, asOfZdt);
+    LinkCacheModule.PORTFOLIO.put(portUuid.toString(), resolvedPortfolio, asOfZdt);
+
+    const link = new TransactionProto();
+    link.setUuid(txnUuid.toUUIDProto());
+    link.setAsOf(asOf);
+    link.setIsLink(true);
+    links.push(link);
+  }
+
+  if (global.gc) global.gc();
+  const heapBefore = process.memoryUsage().heapUsed;
+  const t0 = process.hrtime.bigint();
+  let sink = 0;
+  for (const link of links) {
+    const t = new Transaction(link);
+    // Trigger lazy hydrate via getter that calls ensureHydrated.
+    const name = t.proto.getIsLink() ? "" : t.proto.getTradeName();
+    // Workaround: TS wrappers' ensureHydrated is private and accessors
+    // on Transaction are reads through proto. Hit a typed accessor:
+    const portfolio = t.getPortfolio();
+    if (portfolio) sink++;
+    if (name === "" && portfolio) sink++;
+  }
+  const t1 = process.hrtime.bigint();
+  const heapAfter = process.memoryUsage().heapUsed;
+
+  const elapsedNs = Number(t1 - t0);
+  const elapsedMs = elapsedNs / 1e6;
+  const perOpUs = elapsedNs / n / 1000;
+  const heapDeltaKb = (heapAfter - heapBefore) / 1024;
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `N=${n.toString().padStart(6)}  elapsed=${elapsedMs.toFixed(2).padStart(9)} ms  ` +
+    `per_op=${perOpUs.toFixed(2).padStart(8)} us  ` +
+    `heap_delta=${heapDeltaKb.toFixed(2).padStart(8)} KiB  reads=${sink}`
+  );
+
+  for (const u of txnUuids) LinkCacheModule.TRANSACTION.evict(u);
+  for (const u of portUuids) LinkCacheModule.PORTFOLIO.evict(u);
+}
+
+// Wrap in describe so jest treats it as a suite; the test body is the bench.
+describe("lazy-hydrate bench", () => {
+  test("Transaction across 10/100/1000/10000 sizes", () => {
+    // eslint-disable-next-line no-console
+    console.log("# ts bench: lazy-hydrate Transaction via pre-warmed LinkCache");
+    for (const n of SIZES) runBench(n);
+  }, 60_000);
+});

package/node/wrappers/models/portfolio/portfolio.d.ts

@@ -2,10 +2,28 @@ import { PortfolioProto } from "../../../fintekkers/models/portfolio/portfolio_p
 import { FieldProto } from "../../../fintekkers/models/position/field_pb";
 import { ZonedDateTime } from "../utils/datetime";
 import { UUID } from "../utils/uuid";
+import LinkResolver from "../../util/link-resolver";
 declare class Portfolio {
     proto: PortfolioProto;
     constructor(proto: PortfolioProto);
     toString(): string;
+    isLink(): boolean;
+    /**
+     * Async hydration via `LinkResolver`. Mirrors `Security.hydrate()`.
+     * Returns `this` so it can be chained:
+     *
+     *   const p = await new Portfolio(linkProto).hydrate();
+     *   console.log(p.getPortfolioName());
+     */
+    hydrate(resolver?: LinkResolver): Promise<this>;
+    /**
+     * Lazy hydration. On a link-mode proto, swap in the resolved proto from
+     * LinkCache. On cache miss, throws — caller must pre-warm via
+     * `await portfolio.hydrate()` or LinkResolver. Cache-only by design (same
+     * rationale as Security wrapper: keeps the sync getter API).
+     * See docs/adr/lazy-link-hydration.md.
+     */
+    private ensureHydrated;
     getID(): UUID;
     getAsOf(): ZonedDateTime;
     getPortfolioName(): string;

package/node/wrappers/models/portfolio/portfolio.js

@@ -1,14 +1,105 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const field_pb_1 = require("../../../fintekkers/models/position/field_pb");
 const datetime_1 = require("../utils/datetime");
 const uuid_1 = require("../utils/uuid");
+const LinkCacheModule = __importStar(require("../../util/link-cache"));
+const link_resolver_1 = __importDefault(require("../../util/link-resolver"));
 class Portfolio {
     constructor(proto) {
         this.proto = proto;
     }
     toString() {
-        return this.getPortfolioName();
+        return this.isLink() ? `<link ${this.getID().toString()}>` : this.getPortfolioName();
+    }
+    isLink() {
+        return this.proto.getIsLink();
+    }
+    /**
+     * Async hydration via `LinkResolver`. Mirrors `Security.hydrate()`.
+     * Returns `this` so it can be chained:
+     *
+     *   const p = await new Portfolio(linkProto).hydrate();
+     *   console.log(p.getPortfolioName());
+     */
+    hydrate(resolver) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.proto.getIsLink())
+                return this;
+            const uuidProto = this.proto.getUuid();
+            if (!uuidProto) {
+                throw new Error("Cannot hydrate a link-mode Portfolio with no UUID set.");
+            }
+            const uuid = uuid_1.UUID.fromU8Array(uuidProto.getRawUuid_asU8());
+            const asOfProto = (_a = this.proto.getAsOf()) !== null && _a !== void 0 ? _a : undefined;
+            const r = resolver !== null && resolver !== void 0 ? resolver : link_resolver_1.default.getDefault();
+            const resolved = yield r.getPortfolio(uuid, asOfProto);
+            this.proto = resolved.proto;
+            return this;
+        });
+    }
+    /**
+     * Lazy hydration. On a link-mode proto, swap in the resolved proto from
+     * LinkCache. On cache miss, throws — caller must pre-warm via
+     * `await portfolio.hydrate()` or LinkResolver. Cache-only by design (same
+     * rationale as Security wrapper: keeps the sync getter API).
+     * See docs/adr/lazy-link-hydration.md.
+     */
+    ensureHydrated() {
+        if (!this.proto.getIsLink())
+            return;
+        const uuidProto = this.proto.getUuid();
+        if (!uuidProto) {
+            throw new Error("Cannot read fields on link-mode Portfolio with no UUID set.");
+        }
+        const uuidKey = uuid_1.UUID.fromU8Array(uuidProto.getRawUuid_asU8()).toString();
+        const asOfProto = this.proto.getAsOf();
+        const asOf = asOfProto ? new datetime_1.ZonedDateTime(asOfProto) : null;
+        const cached = LinkCacheModule.PORTFOLIO.get(uuidKey, asOf);
+        if (cached) {
+            this.proto = cached;
+            return;
+        }
+        throw new Error(`Cannot read fields on link-mode Portfolio uuid=${uuidKey} `
+            + `— LinkCache miss. Call \`await portfolio.hydrate()\` first, `
+            + `or pre-warm via LinkResolver. `
+            + `See docs/adr/lazy-link-hydration.md.`);
     }
     getID() {
         const uuid = this.proto.getUuid();
@@ -23,6 +114,7 @@ class Portfolio {
         return new datetime_1.ZonedDateTime(asOf);
     }
     getPortfolioName() {
+        this.ensureHydrated();
         return this.proto.getPortfolioName();
     }
     getFields() {

package/node/wrappers/models/portfolio/portfolio.js.map

@@ -1 +1 @@
-{"version":3,"file":"portfolio.js","sourceRoot":"","sources":["portfolio.ts"],"names":[],"mappings":";;AACA,2EAA0E;AAC1E,gDAAkD;AAClD,wCAAqC;AAErC,MAAM,SAAS;IAGX,YAAY,KAAqB;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,QAAQ;QACJ,OAAO,IAAI,CAAC,gBAAgB,EAAE,CAAC;IACnC,CAAC;IAED,KAAK;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAC1D,OAAO,WAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAG,CAAC,eAAe,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAC1D,OAAO,IAAI,wBAAa,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,gBAAgB;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;IACzC,CAAC;IAED,SAAS;QACL,OAAO,CAAC,qBAAU,CAAC,EAAE,EAAE,qBAAU,CAAC,SAAS,EAAE,qBAAU,CAAC,YAAY,EAAE,qBAAU,CAAC,cAAc,CAAC,CAAC;IACrG,CAAC;IAED,QAAQ,CAAC,KAAiB;QACtB,QAAQ,KAAK,EAAE;YACX,KAAK,qBAAU,CAAC,EAAE,CAAC;YACnB,KAAK,qBAAU,CAAC,YAAY;gBACxB,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;YACxB,KAAK,qBAAU,CAAC,KAAK;gBACjB,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1B,KAAK,qBAAU,CAAC,cAAc;gBAC1B,OAAO,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACnC;gBACI,MAAM,IAAI,KAAK,CAAC,0CAA0C,KAAK,EAAE,CAAC,CAAC;SAC1E;IACL,CAAC;CACJ;AAGD,kBAAe,SAAS,CAAC"}
+{"version":3,"file":"portfolio.js","sourceRoot":"","sources":["portfolio.ts"],"names":[],"mappings":"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"}

package/node/wrappers/models/portfolio/portfolio.ts

@@ -2,6 +2,8 @@ import { PortfolioProto } from "../../../fintekkers/models/portfolio/portfolio_p
 import { FieldProto } from "../../../fintekkers/models/position/field_pb";
 import { ZonedDateTime } from "../utils/datetime";
 import { UUID } from "../utils/uuid";
+import * as LinkCacheModule from "../../util/link-cache";
+import LinkResolver from "../../util/link-resolver";
 
 class Portfolio {
     proto: PortfolioProto;
@@ -11,7 +13,61 @@ class Portfolio {
     }
 
     toString(): string {
-        return this.getPortfolioName();
+        return this.isLink() ? `<link ${this.getID().toString()}>` : this.getPortfolioName();
+    }
+
+    isLink(): boolean {
+        return this.proto.getIsLink();
+    }
+
+    /**
+     * Async hydration via `LinkResolver`. Mirrors `Security.hydrate()`.
+     * Returns `this` so it can be chained:
+     *
+     *   const p = await new Portfolio(linkProto).hydrate();
+     *   console.log(p.getPortfolioName());
+     */
+    async hydrate(resolver?: LinkResolver): Promise<this> {
+        if (!this.proto.getIsLink()) return this;
+        const uuidProto = this.proto.getUuid();
+        if (!uuidProto) {
+            throw new Error("Cannot hydrate a link-mode Portfolio with no UUID set.");
+        }
+        const uuid = UUID.fromU8Array(uuidProto.getRawUuid_asU8());
+        const asOfProto = this.proto.getAsOf() ?? undefined;
+        const r = resolver ?? LinkResolver.getDefault();
+        const resolved = await r.getPortfolio(uuid, asOfProto);
+        this.proto = resolved.proto;
+        return this;
+    }
+
+    /**
+     * Lazy hydration. On a link-mode proto, swap in the resolved proto from
+     * LinkCache. On cache miss, throws — caller must pre-warm via
+     * `await portfolio.hydrate()` or LinkResolver. Cache-only by design (same
+     * rationale as Security wrapper: keeps the sync getter API).
+     * See docs/adr/lazy-link-hydration.md.
+     */
+    private ensureHydrated(): void {
+        if (!this.proto.getIsLink()) return;
+        const uuidProto = this.proto.getUuid();
+        if (!uuidProto) {
+            throw new Error("Cannot read fields on link-mode Portfolio with no UUID set.");
+        }
+        const uuidKey = UUID.fromU8Array(uuidProto.getRawUuid_asU8()).toString();
+        const asOfProto = this.proto.getAsOf();
+        const asOf = asOfProto ? new ZonedDateTime(asOfProto) : null;
+        const cached = LinkCacheModule.PORTFOLIO.get(uuidKey, asOf);
+        if (cached) {
+            this.proto = cached;
+            return;
+        }
+        throw new Error(
+            `Cannot read fields on link-mode Portfolio uuid=${uuidKey} `
+            + `— LinkCache miss. Call \`await portfolio.hydrate()\` first, `
+            + `or pre-warm via LinkResolver. `
+            + `See docs/adr/lazy-link-hydration.md.`
+        );
     }
 
     getID(): UUID {
@@ -27,6 +83,7 @@ class Portfolio {
     }
 
     getPortfolioName(): string {
+        this.ensureHydrated();
         return this.proto.getPortfolioName();
     }
 

package/node/wrappers/models/portfolio-price-transaction.lazy-hydrate.test.d.ts

@@ -0,0 +1 @@
+export {};