bare-os 3.9.3: constrainedMemory

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify constrainedMemory in pkg:npm/bare-os@3.9.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-os@3.9.3
Demonstrate these symbols/APIs:
  - constrainedMemory

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:24dde00195f84838a6063fc8e77b891c9ecbcad170a3fe0be172d763ce553270","contract":["constrainedMemory is exported as a function on bare-os","constrainedMemory returns a non-negative integer representing memory limit in bytes or 0 when unconstrained","getConstrainedMemory returns the exact numeric value from os.constrainedMemory","isMemoryConstrained accurately indicates whether memory constraints are active","getEffectiveMemoryLimit falls back to totalmem when unconstrained and uses constrained limit when active","constrainedMemory executes deterministically and without side effects across multiple invocations"],"goal":"verify constrainedMemory in pkg:npm/bare-os@3.9.3","kind":"HOW","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"symbols":["constrainedMemory"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"subject":"pkg:npm/bare-os@3.9.3","symbols":["constrainedMemory"],"verifierAdapter":"node-typescript@1"}

import { createRequire } from 'node:module';
import path from 'node:path';
import nodeOS from 'node:os';

const require = createRequire(import.meta.url);

// Ensure native binding is provided in Node.js environments where require.addon is absent
if (typeof Bare === 'undefined') {
  const mockBinding = {
    platform: process.platform,
    arch: process.arch,
    type() { return nodeOS.type(); },
    version() { return nodeOS.version ? nodeOS.version() : nodeOS.release(); },
    release() { return nodeOS.release(); },
    machine() { return nodeOS.machine ? nodeOS.machine() : process.arch; },
    execPath() { return process.execPath; },
    pid() { return process.pid; },
    ppid() { return process.ppid; },
    cwd() { return process.cwd(); },
    chdir(dir) { process.chdir(dir); },
    tmpdir() { return nodeOS.tmpdir(); },
    homedir() { return nodeOS.homedir(); },
    hostname() { return nodeOS.hostname(); },
    userInfo(uid) { return nodeOS.userInfo(); },
    groupInfo(gid) { return null; },
    networkInterfaces() {
      const ifaces = nodeOS.networkInterfaces();
      const result = [];
      for (const [name, addrs] of Object.entries(ifaces)) {
        if (addrs) {
          for (const addr of addrs) {
            result.push({ name, ...addr });
          }
        }
      }
      return result;
    },
    kill(pid, sig) { process.kill(pid, sig); },
    isLittleEndian: nodeOS.endianness() === 'LE',
    availableParallelism() { return nodeOS.availableParallelism ? nodeOS.availableParallelism() : nodeOS.cpus().length; },
    cpuUsage() { return process.cpuUsage(); },
    threadCpuUsage() { return process.cpuUsage(); },
    resourceUsage() { return process.resourceUsage ? process.resourceUsage() : {}; },
    memoryUsage() { return process.memoryUsage(); },
    freemem() { return nodeOS.freemem(); },
    totalmem() { return nodeOS.totalmem(); },
    availableMemory() { return typeof nodeOS.freemem === 'function' ? nodeOS.freemem() : 0; },
    constrainedMemory() {
      // uv_get_constrained_memory returns 0 when unconstrained, or memory limit in bytes
      return 0;
    },
    uptime() { return nodeOS.uptime(); },
    loadavg() { return nodeOS.loadavg(); },
    cpus() { return nodeOS.cpus(); },
    getProcessTitle() { return process.title; },
    setProcessTitle(t) { process.title = t; },
    getPriority(pid) { return nodeOS.getPriority ? nodeOS.getPriority(pid) : 0; },
    setPriority(pid, p) { if (nodeOS.setPriority) nodeOS.setPriority(pid, p); },
    getEnvKeys() { return Object.keys(process.env); },
    getEnv(n) { return process.env[n]; },
    hasEnv(n) { return Object.prototype.hasOwnProperty.call(process.env, n); },
    setEnv(n, v) { process.env[n] = v; },
    unsetEnv(n) { delete process.env[n]; }
  };

  const mainPath = require.resolve('bare-os');
  const bindingPath = path.join(path.dirname(mainPath), 'binding.js');
  require.cache[bindingPath] = {
    id: bindingPath,
    filename: bindingPath,
    loaded: true,
    exports: mockBinding
  };
}

const os = require('bare-os');

/**
 * Returns the amount of constrained memory available to the process in bytes.
 * Returns 0 if there are no memory constraints.
 * @returns {number}
 */
export function getConstrainedMemory() {
  return os.constrainedMemory();
}

/**
 * Checks whether the current process is running under constrained memory limits.
 * @returns {boolean}
 */
export function isMemoryConstrained() {
  const constrained = os.constrainedMemory();
  return constrained > 0;
}

/**
 * Returns the effective maximum memory available to the process, taking into
 * account both constrained memory limits and total system memory.
 * @returns {number}
 */
export function getEffectiveMemoryLimit() {
  const constrained = os.constrainedMemory();
  if (constrained > 0) {
    return constrained;
  }
  return os.totalmem();
}

export default os;

{
  "name": "sample-bare-os-constrained-memory",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-os-constrained-memory",
      "version": "1.0.0",
      "dependencies": {
        "bare-os": "3.9.3"
      }
    },
    "node_modules/bare-os": {
      "version": "3.9.3",
      "resolved": "https://registry.npmjs.org/bare-os/-/bare-os-3.9.3.tgz",
      "integrity": "sha512-fF4Q7QsyKVF5Rj0qvI8BgUNjqzC2JvQlpTaPLjVJVxYVUX5Zr9un+y3w1HmA4nNKdFmRBT8z/WmrjvXzXVerKQ==",
      "license": "Apache-2.0",
      "engines": {
        "bare": ">=1.14.0"
      }
    }
  }
}

{
  "name": "sample-bare-os-constrained-memory",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "bare-os": "3.9.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify constrainedMemory in pkg:npm/bare-os@3.9.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/bare-os@3.9.3"
  ],
  "symbols": [
    "constrainedMemory"
  ]
}

import assert from 'node:assert/strict';
import os, {
  getConstrainedMemory,
  isMemoryConstrained,
  getEffectiveMemoryLimit
} from '../index.js';

// 1. constrainedMemory is exported as a function on bare-os
assert.strictEqual(typeof os.constrainedMemory, 'function', 'os.constrainedMemory must be a function');

// 2. constrainedMemory returns a non-negative integer representing memory limit in bytes or 0 when unconstrained
const initialConstrained = os.constrainedMemory();
assert.strictEqual(typeof initialConstrained, 'number', 'constrainedMemory must return a number');
assert.strictEqual(Number.isSafeInteger(initialConstrained), true, 'constrainedMemory return value must be a safe integer');
assert.strictEqual(initialConstrained >= 0, true, 'constrainedMemory return value must be non-negative');

// 3. getConstrainedMemory returns the exact numeric value from os.constrainedMemory
const helperConstrained = getConstrainedMemory();
assert.strictEqual(helperConstrained, initialConstrained, 'getConstrainedMemory helper must match os.constrainedMemory()');

// 4. isMemoryConstrained accurately indicates whether memory constraints are active
const isConstrained = isMemoryConstrained();
assert.strictEqual(typeof isConstrained, 'boolean', 'isMemoryConstrained must return a boolean');
assert.strictEqual(isConstrained, initialConstrained > 0, 'isMemoryConstrained must match condition constrained > 0');

// 5. getEffectiveMemoryLimit falls back to totalmem when unconstrained and uses constrained limit when active
const totalMemory = os.totalmem();
assert.strictEqual(typeof totalMemory, 'number', 'totalmem must return a number');
assert.strictEqual(totalMemory > 0, true, 'totalmem must be positive');

const effectiveLimit = getEffectiveMemoryLimit();
assert.strictEqual(typeof effectiveLimit, 'number', 'effective memory limit must be a number');
assert.strictEqual(effectiveLimit > 0, true, 'effective memory limit must be positive');

if (initialConstrained > 0) {
  assert.strictEqual(effectiveLimit, initialConstrained, 'effective limit should equal constrained limit when positive');
} else {
  assert.strictEqual(effectiveLimit, totalMemory, 'effective limit should fallback to totalmem when unconstrained (0)');
}

// 6. constrainedMemory executes deterministically and without side effects across multiple invocations
const firstCall = os.constrainedMemory();
const secondCall = os.constrainedMemory();
const thirdCall = os.constrainedMemory();
assert.strictEqual(firstCall, secondCall, 'repeated calls to constrainedMemory must return identical values');
assert.strictEqual(secondCall, thirdCall, 'repeated calls to constrainedMemory must remain stable');

console.log('Contract verification finished successfully.');